RAML (software) - RAML (software)

RAML
Přípona názvu souboru
.raml
Typ internetového média
aplikace / raml + yaml[n 1]
VyvinulPracovní skupina RAML
Poslední vydání
1.0
(16. května 2016 (2016-05-16)[1])
Rozšířeno zYAML
Standardgithub.com/ raml-org/ raml-spec/kapka/mistr/ verze/ raml-10/ raml-10.md/
webová stránkaRaml.org

RESTful API Modeling Language (RAML) je YAML -založený jazyk pro popis Klidný API.[2] Poskytuje všechny informace potřebné k popisu rozhraní RESTful nebo prakticky RESTful API. Přestože je RAML navržen s ohledem na RESTful API, je schopen popsat API, která nesplňují všechna omezení REST (odtud popis „prakticky RESTful“). Podporuje opětovné použití, umožňuje objevování a sdílení vzorů a usiluje o vznik osvědčených postupů na základě zásluh.[3]

Dějiny

RAML byl poprvé navržen v roce 2013. Původní specifikaci RAML vytvořili Uri Sarid, Emiliano Lesende, Santiago Vacas a Damian Martinez a získala podporu od technologických lídrů jako MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web a API Web Science, Kin Lane, SOA Software a Cisco[4]. Vývoj je řízen pracovní skupinou RAML.[5] Mezi současné signatáře pracovních skupin patří technologičtí lídři z MuleSoft (Uri Sarid, CTO), AngularJS (Misko Hevery, zakladatel projektu), Intuice (Ivan Lazarov, hlavní podnikový architekt), Airware (Peter Rexer, ředitel produktu - vývojářská platforma), Programovatelný web a Věda API (John Musser, zakladatel), Software SOA (Tony Gullotta, ředitel pro rozvoj), Cisco (Jaideep Subedar, hlavní manažer, produktový management - Application Integration Solutions Group), VMware (Kevin Duffey, hlavní inženýr MTS), Akamai Technologies (Rob Daigneau, ředitel architektury pro platformu OPEN API společnosti Akamai) a Restlet (Jerome Louvel, CTO a zakladatel). RAML je ochranná známka společnosti MuleSoft.[6]

Velmi málo stávajících API splňuje přesná kritéria, která mají být klasifikována jako RESTful API. Následně, stejně jako většina iniciativ API v roce 2010, se RAML zpočátku zaměřila na základy prakticky RESTful API včetně zdrojů, metod, parametrů a těl odpovědí, které nemusí být hypermediální. Jak to umožňuje vývoj technologie a trhu, existují plány na přechod k přísněji RESTful API.

Existuje řada důvodů, proč RAML propukl z toho, že je proprietárním jazykem dodavatele, a osvědčil se pro širší komunitu API:[7]

  • RAML byl otevřen spolu s nástroji a analyzátory pro běžné jazyky. Na vývoj RAML bude dohlížet řídící výbor odborníků na API a UX a kolem RAML se vyvíjí vznikající ekosystém nástrojů třetích stran.[8]
  • MuleSoft původně začal používat Swagger (nyní Specifikace OpenAPI ), ale rozhodl se, že je nejvhodnější pro dokumentaci existujícího API, ne pro návrh API od nuly. RAML se vyvinulo z potřeby podpory up-front designu API ve stručném, lidsky orientovaném jazyce[9]
  • Popisy API jsou často podrobné a opakované, což může znesnadnit jejich pochopení a použití, a pomalé přijetí API. RAML zavedla jazykové funkce, které podporují strukturované soubory a dědičnost, které řeší průřezové problémy[10]

Nová organizace pod záštitou Linux Foundation, nazvaná Open API Initiative, byla zřízena v roce 2015 za účelem standardizace popisu Klidný API. Řada společností včetně SmartBear, Google, IBM a Microsoft byli zakládajícími členy.[11][12] SmartBear daroval specifikaci Swagger nové skupině. Skupina také zvažuje RAML a Blueprint API.[13][14]

Příklad

Toto je příklad souboru RAML. Stejně jako u YAML, odsazení ukazuje vnoření.

 1   #% RAML 0,8 2  3   titul: World Music API 4   baseUri: http://example.api.com/{version} 5   verze: v1 6   rysy: 7     - stránkovaný: 8         queryParameters: 9           stránky:10             popis: Počet stránek, které se mají vrátit11             typ: číslo12     - zajištěné: !zahrnout http://raml-example.com/zabezpečený.yml13   / písně:14     je: [ stránkovaný, zajištěné ]15     dostat:16       queryParameters:17         žánr:18           popis: filtrovat skladby podle žánru19     pošta:20     / {songId}:21       dostat:22         odpovědi:23           200:24             tělo:25               aplikace / JSON:26                 schéma: |27                   {"$ schema": "http://json-schema.org/schema",28                     "type": "object",29                     "description": "Kanonická píseň",30                     "vlastnosti": {31                       "title": {"type": "string"},32                       "artist": {"type": "string"}33                     },34                     "required": ["title", "artist"]35                   }36               aplikace / xml:37       vymazat:38         popis: |39           Tato metoda * smaže * samostatnou skladbu **

Některé zajímavosti:

  • řádek 7, 12: definuje vlastnosti vyvolané na více místech
  • řádek 12: Zahrnout soubor
  • řádek 13, 14: definujte "zdrojový" datový typ "/ písně"; používá dříve definované vlastnosti
  • řádek 15, 19, 37: definuje HTTP metody
  • řádek 25, 36: Typy MIME.

Brány API podporující RAML

Dále můžete převést svoji specifikaci RAML na kteroukoli z nich OpenAPI nebo API Blueprint použitím APIMATICKÉ, což vám umožní používat další brány API.

Viz také

Alternativní RESTful modelovací jazyky

Poznámky

  1. ^ Není registrován u IANA

Reference

  1. ^ "Oznámení RAML 1.0 GA | Blog RAML". Citováno 11. srpna 2016.
  2. ^ „RAML 1.0“. Citováno 26. května 2017.
  3. ^ „RAML - RESTful API Modeling Language“. Citováno 15. července 2014.
  4. ^ „RAML nebo OpenAPI - A co obojí? - Integrace DZone“. dzone.com. Citováno 2017-10-04.
  5. ^ „Pracovní skupina RAML“.
  6. ^ „RAML - podrobnosti ochranné známky“. 26. května 2017.
  7. ^ „Proč je RAML více než jiná vlastní specifikace“. 11. dubna 2014.
  8. ^ „API Design Tooling from RAML“. 3. března 2014.
  9. ^ „Anypoint for APIs: An Interview with Uri Sarid“. 25. února 2014.
  10. ^ "Příklad návrhu API pomocí RAML". 11. dubna 2014.
  11. ^ „SmartBear, Linux Foundation zahajuje iniciativu Open API Initiative to Evolve Swagger“. Programovatelný web. 2015-11-10. Citováno 2016-04-21.
  12. ^ „Nový projekt spolupráce, který rozšíří specifikace Swagger pro vytváření propojených aplikací a služeb“. www.linuxfoundation.org. Archivovány od originál dne 2016-04-27. Citováno 2016-04-22.
  13. ^ Montcheuil, Yves de. „V roce 2016 se krystalizuje potřeba metajazyka API.“. InfoWorld. Citováno 2016-04-25.
  14. ^ „Amazon API Gateway nyní podporuje import definic Swagger“. InfoQ. Citováno 2016-04-25.

externí odkazy