Úvod do RAML - modelového jazyka RESTful API

Tento článok je súčasťou série: • Úvod do RAML - The RESTful API Modeling Language (aktuálny článok) • Eliminácia nadbytočnosti v RAML pomocou typov a vlastností zdrojov

• Modulárna RAML s použitím inklúzií, knižníc, prekrytí a rozšírení

• Definujte vlastné vlastnosti RAML pomocou anotácií

1. Prehľad

V tomto článku predstavujeme RESTful API Modeling Language (RAML), vendorsky neutrálny jazyk otvorenej špecifikácie založený na YAML 1.2 a JSON na popis RESTful API.

Pri demonštrácii toho, ako definovať jednoduché API založené na JSON, sa budeme venovať základnej syntaxi a štruktúre súborov RAML 1.0. Ukážeme tiež, ako zjednodušiť údržbu súborov RAML pomocou zahŕňa. A ak máte staršie rozhrania API, ktoré používajú schému JSON, ukážeme si, ako začleniť schémy do RAML.

Potom predstavíme niekoľko nástrojov, ktoré môžu vylepšiť vašu cestu k RAML, vrátane nástrojov na tvorbu, generátorov dokumentácie a ďalších.

Na záver zhrnieme popis súčasného stavu špecifikácie RAML.

2. Definovanie vášho API (Vytvorenie .raml súbor)

Rozhranie API, ktoré definujeme, je pomerne jednoduché: vzhľadom na typy entít Foo, definujte základné operácie CRUD a niekoľko operácií dotazu. Tu sú zdroje, ktoré definujeme pre naše API:

  • GET / api / v1 / foos
  • POST / api / v1 / foos
  • GET / api / v1 / foos / {id}
  • PUT / api / v1 / foos / {id}
  • DELETE / api / v1 / foos / {id}
  • GET / api / v1 / foos / name / {name}
  • GET / api / v1 / foos? Name = {name} & ownerName = {ownerName}

Definujme naše API tak, aby bolo bez štátnej príslušnosti, používalo základné overenie HTTP, a aby bolo doručované šifrované cez HTTPS. Na záver si vyberieme JSON pre náš formát prenosu údajov (podporuje sa aj XML).

2.1. Nastavenia na koreňovej úrovni

Začneme vytvorením jednoduchého textového súboru s názvom api.raml (the .raml odporúča sa predpona; názov je ľubovoľný) a do prvého riadku pridajte hlavičku verzie RAML. Na koreňovej úrovni súboru definujeme nastavenia, ktoré sa vzťahujú na celé API:

#% RAML 1.0 title: Baeldung Foo REST Services API using Data Types version: v1 protocols: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json

Všimnite si na riadku 3 použitie zátvoriek {} okolo slova „verzia„. Takto hovoríme RAML, že „verzia “ odkazuje na nehnuteľnosť a má byť rozšírená. Preto skutočné baseUri bude: //myapi.mysite.com/v1

[Poznámka: verzia majetok je voliteľný a nemusí byť súčasťou baseUri.]

2.2. Bezpečnosť

Zabezpečenie je tiež definované na koreňovej úrovni systému Windows .raml spis. Pridajme teda našu základnú definíciu bezpečnostnej schémy HTTP:

securitySchemes: basicAuth: description: Každá požiadavka musí obsahovať hlavičky potrebné pre základný typ autentifikácie: Základné autentifikácia popísaná By: hlavičky: Autorizácia: description: Používa sa na odoslanie Base64 - kódovaného "užívateľského mena: hesla" prihlasovacích údajov typu: odpovede reťazca: 401: description: | Neoprávnené. Buď je uvedená kombinácia používateľského mena a hesla neplatná alebo používateľ nemá povolený prístup k obsahu poskytovanému požadovanou adresou URL.

2.3. Dátové typy

Ďalej definujeme dátové typy, ktoré bude naše API používať:

typy: Foo: typ: vlastnosti objektu: id: požadované: true typ: celé číslo meno: požadované: true typ: vlastník reťazcaName: požadované: false typ: reťazec

Vyššie uvedený príklad používa na definovanie našich dátových typov rozšírenú syntax. RAML poskytuje niektoré syntaktické skratky, aby boli naše definície typov menej podrobné. Tu je časť s ekvivalentnými typmi údajov, ktorá používa tieto skratky:

typy: Foo: properties: id: integer name: string ownerName ?: string Error: properties: code: integer message: string

„?“ znak nasledujúci za názvom vlastnosti vyhlasuje, že vlastnosť nie je požadovaná.

2.4. Zdroje

Teraz definujeme zdroj najvyššej úrovne (URI) nášho API:

/ foos:

2.5. Parametre URI

Ďalej rozšírime zoznam zdrojov zostavením z nášho zdroja najvyššej úrovne:

/ foos: / {id}: / name / {name}:

Tu zložené zátvorky {} okolo názvov vlastností definujú parametre URI. Predstavujú zástupné symboly v každom URI a neodkazujú na vlastnosti súboru RAML na koreňovej úrovni, ako sme videli vyššie v baseUri vyhlásenie. Pridané riadky predstavujú zdroje / foos / {id} a / foos / name / {name}.

2.6. Metódy

Ďalším krokom je definovanie metód HTTP, ktoré sa vzťahujú na každý zdroj:

/ foos: get: post: / {id}: get: put: delete: / name / {name}: get:

2.7. Parametre dopytu

Teraz definujeme spôsob dotazovania foos zber pomocou parametrov dotazu. Upozorňujeme, že parametre dotazu sú definované pomocou rovnakej syntaxe, ktorú sme použili vyššie pre dátové typy:

/ foos: get: description: Zoznam všetkých kritérií vyhovujúcich požiadavkám Foos, ak sú poskytnuté; inak vypíš všetky Foos queryParameters: name ?: string ownerName ?: string

2.8. Odpovede

Teraz, keď sme definovali všetky zdroje pre naše API, vrátane parametrov URI, metód HTTP a parametrov dotazu, je čas definovať očakávané odpovede a stavové kódy. Formáty odpovedí sú zvyčajne definované vzhľadom na dátové typy a príklady.

Kvôli spätnej kompatibilite so staršou verziou RAML je možné namiesto dátových typov použiť schému JSON. Schému JSON si predstavíme v sekcii 3.

[Poznámka: V úryvkoch kódu nižšie riadok obsahujúci iba tri bodky (…) naznačuje, že niektoré riadky sú kvôli stručnosti preskočené.]

Začnime jednoduchou operáciou GET / foos / {id}:

/ foos: ... / {id}: get: description: Získajte Foo podľa id odpovede: 200: body: application / json: type: Foo príklad: {"id": 1, "name": "First Foo" }

Tento príklad ukazuje, že vykonaním požiadavky GET na prostriedku / foos / {id}, mali by sme dostať späť zhodu Foo vo forme objektu JSON a stavového kódu HTTP 200.

Takto by sme definovali požiadavku GET na serveri / foos zdroj:

/ foos: get: description: Zoznam všetkých kritérií vyhovujúcich požiadavkám Foos, ak sú poskytnuté; inak vypíš všetky Foos queryParametre: meno ?: vlastník reťazcaName ?: odpovede reťazca: 200: body: application / json: typ: Foo [] príklad: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}]

Všimnite si použitie hranatých zátvoriek [] pripojených k Foo typu. To ukazuje, ako by sme definovali telo odpovede obsahujúce pole Foo objekty, príkladom je pole objektov JSON.

2.9. Orgán žiadosti

Ďalej definujeme orgány žiadosti, ktoré zodpovedajú každej požiadavke POST a PUT. Začnime vytvorením nového Foo objekt:

/ foos: ... post: description: Vytvorte nový Foo body: application / json: type: Foo príklad: {"id": 5, "name": "Another foo"} odpovede: 201: body: application / json : type: Foo príklad: {"id": 5, "name": "Another foo"}

2.10. Stavové kódy

Vo vyššie uvedenom príklade si všimnite, že pri vytváraní nového objektu vrátime stav HTTP 201. Operácia PUT na aktualizáciu objektu vráti stav HTTP 200, pričom použije rovnaké orgány žiadosti a odpovede ako operácia POST.

Okrem očakávaných odpovedí a stavových kódov, ktoré vrátime, keď je požiadavka úspešná, môžeme definovať druh odpovede a stavový kód, ktorý sa dá očakávať v prípade chyby.

Pozrime sa, ako by sme definovali očakávanú odpoveď na požiadavku GET na serveri / foos / {id} prostriedok, keď sa nenájde žiadny zdroj s daným ID:

 404: body: application / json: type: Príklad chyby: {"message": "Nenašiel sa", "kód": 1001}

3. RAML so schémou JSON

Predtým dátové typy boli zavedené v RAML 1.0, objekty, orgány žiadostí a orgány odpovedí boli definované pomocou schémy JSON.

Použitím dátové typy môže byť veľmi výkonný, ale existujú prípady, keď stále chcete použiť schému JSON. V RAML 0.8 ste definovali svoje schémy pomocou koreňovej úrovne schémy oddiel.

To stále platí, ale odporúča sa použiť typy oddiel od použitia schémy môže byť v budúcej verzii zastarané. Oboje typy a schémy, ako aj typu a schéma, sú synonymá.

Takto by ste definovali typ objektu Foo na koreňovej úrovni súboru .raml súbor pomocou schémy JSON:

typy: foo: | {"$ schema": "//json-schema.org/schema", "type": "object", "description": "Foo details", "properties": {"id": {"type": integer }, "name": {"type": "string"}, "ownerName": {"type": "string"}}, "required": ["id", "name"]}

A takto by ste odkázali na schému v GET / foos / {id} definícia zdroja:

/ foos: ... / {id}: get: description: Získajte Foo podľa jeho id odpovedí: 200: body: application / json: type: foo ...

4. Refaktoring s Zahrňuje

Ako vidíme z vyššie uvedených častí, naše API je stále dosť podrobné a opakujúce sa.

Špecifikácia RAML poskytuje mechanizmus zahrnutia, ktorý nám umožňuje externalizovať opakované a zdĺhavé časti kódu.

Našu definíciu API môžeme refaktorovať pomocou zahrnutia, takže je stručnejšia a menej pravdepodobná, že bude obsahovať typy chýb, ktoré sú výsledkom metodiky „kopírovať / vložiť / opraviť všade“.

Napríklad môžeme dať dátový typ pre a Foo objekt v súbore typy / Foo.raml a typ pre Chyba namietať v typy / Error.raml. Potom náš typy časť bude vyzerať takto:

typy: Foo:! zahrnúť typy / Foo.raml Chyba:! zahrnúť typy / Error.raml

A ak namiesto toho použijeme schému JSON, naša typy časť môže vyzerať takto:

typy: foo:! zahrnúť schémy / foo.json chyba:! zahrnúť schémy / error.json

5. Dokončenie API

Po externalizácii všetkých dátových typov a príkladov do ich súborov môžeme naše API refaktorovať pomocou nástroja include:

#% RAML 1.0 title: Baeldung Foo REST Services API version: v1 protocols: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application / json zabezpečenéBy: basicAuth securitySchemes: basicAuth: description: Každá požiadavka musí obsahovať hlavičky potrebné pre základný typ autentifikácie: Základné autentifikácia popísaná By: hlavičky: Autorizácia: popis: Používa sa na odoslanie Base64 zakódovaných "používateľské meno: heslo" prihlasovacích údajov typ: reťazcové odpovede: 401: popis: | Neoprávnené. Buď je zadaná kombinácia používateľského mena a hesla neplatná alebo používateľ nemá povolený prístup k obsahu poskytovanému požadovanou adresou URL. typy: Foo:! zahrnúť typy / Foo.raml Chyba:! zahrnúť typy / Error.raml / foos: get: description: Zoznam všetkých Foos zodpovedajúcich kritériám dotazu, ak sú poskytnuté; v opačnom prípade uveďte všetky Foos queryParameters: name ?: string ownerName ?: string response: 200: body: application / json: type: Foo [] example:! include examples / Foos.json post: description: Create a new Foo body: application / json: type: Foo príklad:! include examples / Foo.json odpovede: 201: body: application / json: type: Foo príklad:! include examples / Foo.json / {id}: get: description: Get a Foo by id reakcie: 200: body: application / json: type: Foo príklad:! include examples / Foo.json 404: body: application / json: type: Error example:! include examples / Error.json put: description: Update a Foo by id body: application / json: type: Foo príklad:! zahrnúť príklady / Foo.json odpovede: 200: body: application / json: type: Foo príklad:! zahrnúť príklady / Foo.json 404: body: application / json: type : Príklad chyby:! Include examples / Error.json delete: description: Delete a Foo by id response: 204: 404: body: application / json: type: Error example:! Include examples / Error.json / name / {name} : získať: popis: Zoznam všetkých Foos s určitým menom odpovede: 200: body: application / json: type: Foo [] príklad:! Zahrnúť príklady / Foos.json

6. Nástroje RAML

Jednou z veľkých vecí na RAML je podpora nástrojov.

Existujú nástroje na analýzu, validáciu a tvorbu API RAML; nástroje na generovanie klientskeho kódu; nástroje na generovanie dokumentácie API vo formátoch HTML a PDF; a nástroje, ktoré nám pomáhajú pri testovaní na špecifikáciu RAML API.

Existuje dokonca aj nástroj, ktorý prevedie Swagger JSON API na RAML.

Tu je výber dostupných nástrojov:

  • API Designer - webový nástroj zameraný na rýchly a efektívny dizajn API
  • API Workbench - IDE na navrhovanie, budovanie, testovanie a dokumentáciu RESTful API, ktoré podporuje RAML 0.8 aj 1.0
  • RAML Cop - nástroj na overovanie súborov RAML
  • RAML pre JAX-RS - sada nástrojov na generovanie kostry aplikačného kódu Java + JAX-RS zo špecifikácie RAML alebo na generovanie špecifikácie RAML z existujúcej aplikácie JAX-RS
  • RAML Sublime Plugin - doplnok na zvýraznenie syntaxe pre textový editor Sublime
  • RAML to HTML - nástroj na generovanie HTML dokumentácie z RAML
  • raml2pdf - nástroj na generovanie PDF dokumentácie z RAML
  • RAML2Wiki - nástroj na generovanie dokumentácie Wiki (pomocou značiek Confluence / JIRA)
  • SoapUI RAML Plugin - doplnok RAML pre populárnu funkčnú sadu testovacích rozhraní API SoapUI
  • Vigia - integračný testovací balík schopný generovať testovacie prípady na základe definície RAML

Kompletný zoznam nástrojov RAML a súvisiacich projektov nájdete na stránke Projekty RAML.

7. Aktuálny stav RAML

Špecifikácia RAML 1.0 (RC) získala status kandidáta na vydanie 3. novembra 2015 a v čase písania tohto článku sa mala finálna verzia 1.0 dokončiť v priebehu mesiaca.

Jeho predchodca, RAML 0.8, vyšiel pôvodne na jeseň 2014 a stále ho podporuje nespočetné množstvo nástrojov.

8. Ďalšie čítanie

Tu je niekoľko odkazov, ktoré by sa nám mohli pri našej ceste RAML hodiť.

  • RAML.org - oficiálna stránka špecifikácie RAML
  • json-schema.org - domov schémy JSON
  • Pochopenie schémy JSON
  • Generátor schémy JSON
  • Stránka Wikipedia RAML

9. Záver

Tento článok predstavil RESTful API Modeling Language (RAML). Demonštrovali sme niekoľko základných syntaxov pre zápis jednoduchej špecifikácie API pomocou špecifikácie RAML 1.0 (RC).

A videli sme spôsoby, ako urobiť naše definície stručnejšími pomocou syntaktických skratiek a externalizácie príkladov, dátových typov a schém do súborov „zahrnutia“.

Potom sme predstavili kolekciu výkonných nástrojov, ktoré spolupracujú so špecifikáciami RAML, ktoré pomáhajú pri každodenných úlohách týkajúcich sa návrhu, vývoja, testovania a dokumentácie API.

S blížiacim sa oficiálnym vydaním verzie 1.0 špecifikácie, spojenou s drvivou podporou vývojárov nástrojov, to vyzerá, že RAML tu zostane.

Ďalšie » Eliminujte prepúšťanie v RAML pomocou typov a vlastností zdrojov

Populárne Príspevky

Posledné príspevky

Copyright sk.streamalism.org 2024
$config[zx-auto] not found$config[zx-overlay] not found