Eliminujte prepúšťanie v RAML pomocou typov a vlastností zdrojov

Tento článok je súčasťou série: • Úvod do RAML - modelového jazyka RESTful API

• Eliminujte redundancie v RAML pomocou typov a vlastností zdrojov (aktuálny článok) • Modulárna RAML s využitím inklúzií, knižníc, prekrytí a rozšírení

• Definujte vlastné vlastnosti RAML pomocou anotácií

1. Prehľad

V našom článku tutoriálu RAML sme predstavili RESTful API Modeling Language a vytvoril jednoduchú definíciu API založenú na jednej entite, ktorá sa volá Foo. Teraz si predstavte API v reálnom svete, v ktorom máte niekoľko prostriedkov typu entity, pričom všetky majú rovnaké alebo podobné operácie GET, POST, PUT a DELETE. Uvidíte, ako sa vaša dokumentácia k rozhraniu API môže rýchlo stať zdĺhavou a opakujúcou sa.

V tomto článku si ukážeme, ako sa používanie typy zdrojov a črty funkcie v RAML môžu eliminovať nadbytočnosť v definíciách zdrojov a metód extrakciou a parametrizáciou bežných sekcií, čím sa eliminujú chyby pri kopírovaní a vkladaní a zároveň budú vaše definície API stručnejšie.

2. Naše API

S cieľom preukázať výhody typy zdrojov a črty, rozšírime naše pôvodné API pridaním zdrojov pre druhý typ entity s názvom Bar. Tu sú zdroje, ktoré tvoria naše revidované API:

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

3. Rozpoznávanie vzorov

Keď si prečítame zoznam zdrojov v našom API, začneme vidieť, ako sa objavujú niektoré vzory. Napríklad existuje vzor pre URI a metódy používané na vytváranie, čítanie, aktualizáciu a mazanie jednotlivých entít a existuje vzor pre URI a metódy používané na načítanie zbierok entít. Zbierka a vzor položky zbierky sú jedným z najbežnejších vzorov používaných na extrakciu typy zdrojov v definíciách RAML.

Pozrime sa na niekoľko častí nášho API:

[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é.]

/ foos: get: description: | Uveďte zoznam všetkých kritérií zodpovedajúcich kritériám vyhľadávania, ak sú uvedené; v opačnom prípade vypíšte zoznam všetkých foo dotazov Parametre: meno ?: vlastník reťazcaName ?: odpovede reťazca: 200: body: application / json: type: Foo [] príspevok: description: Vytvorte nový foo body: application / json: type: Foo odpovede: 201: body: application / json: type: Foo ... / bars: get: description: | Zoznam všetkých pruhov zodpovedajúcich kritériám dotazu, ak sú uvedené; v opačnom prípade uveďte zoznam všetkých pruhov queryParameters: name ?: string ownerName ?: string response: 200: body: application / json: type: Bar [] post: description: Create a new bar body: application / json: type: Bar response: 201: body: application / json: type: Bar

Keď porovnáme definície RAML súboru / foos a / bary zdrojov, vrátane použitých metód HTTP, môžeme vidieť niekoľko redundancií medzi rôznymi vlastnosťami každého z nich a opäť vidíme, že sa začínajú objavovať vzory.

Kdekoľvek existuje vzor v definícii zdroja alebo metódy, je tu príležitosť použiť RAML typ zdroja alebo vlastnosť.

4. Typy zdrojov

Za účelom implementácie vzorov nájdených v API, typy zdrojov používať vyhradené a používateľom definované parametre obklopené dvojitými zátvorkami (<>).

4.1 Rezervované parametre

V definíciách typov prostriedkov môžu byť použité dva vyhradené parametre:

  • <> predstavuje celý URI (po baseURI) a
  • <> predstavuje časť identifikátora URI, ktorá nasleduje za lomkou úplne doprava (/) a ignoruje všetky zložené zátvorky {}.

Keď sa spracúvajú v rámci definície zdroja, ich hodnoty sa počítajú na základe definovaného zdroja.

Vzhľadom na zdroj / foos, napríklad, <> by sa hodnotilo na „/ foos“ a <>hodnotí ako „foos“.

Vzhľadom na zdroj / foos / {fooId}, <> vyhodnotí ako „/ foos / {fooId}“ a <>hodnotí ako „foos“.

4.2 Užívateľom definované parametre

A typ zdroja definícia môže obsahovať aj užívateľom definované parametre. Na rozdiel od vyhradených parametrov, ktorých hodnoty sa určujú dynamicky na základe definovaného prostriedku, používateľom definované parametre musia mať priradené hodnoty vždy, keď typ zdroja je použité a tieto hodnoty sa nezmenia.

Užívateľom definované parametre môžu byť deklarované na začiatku a typ zdroja definícia, aj keď sa to nevyžaduje a nie je to bežná prax, pretože čitateľ môže zvyčajne zistiť svoje zamýšľané použitie vzhľadom na ich mená a kontexty, v ktorých sa používajú.

4.3 Funkcie parametrov

Niekoľko užitočných textových funkcií je k dispozícii na použitie všade, kde sa parameter používa na transformáciu rozšírenej hodnoty parametra, keď sa spracuje v definícii prostriedku.

Tu sú dostupné funkcie pre transformáciu parametrov:

  • !singularizovať
  • !pluralizovať
  • !veľké písmená
  • !malými písmenami
  • !horná veľká kamera
  • !dolná kamera
  • !upperunderscorecase
  • !lowerunderscorecase
  • !upperhyphencase
  • !lowerhyphencase

Funkcie sa aplikujú na parameter pomocou nasledujúcej konštrukcie:

<<parameterName | !functionName>>

Ak potrebujete na dosiahnutie požadovanej transformácie použiť viac ako jednu funkciu, mali by ste každý názov funkcie oddeliť symbolom potrubia („|“) a pred každú použitú funkciu vložiť výkričník (!).

Napríklad vzhľadom na zdroj / foos, kde <<resourcePathName>> vyhodnotí sa ako „foos“:

  • <<resourcePathName | !singularizovať>> ==> „foo“
  • <<resourcePathName | !veľké písmená>> ==> „FOOS“
  • <<resourcePathName | !singularizovať | !veľké písmená>> ==> „FOO“

A vzhľadom na zdroj / bary / {barId}, kde <<resourcePathName>> vyhodnotí sa ako „pruhy“:

  • <<resourcePathName | !veľké písmená>> ==> „TYČE“
  • <<resourcePathName | !horná veľká kamera>> ==> „Bar“

5. Extrahovanie typu zdroja pre zbierky

Poďme refaktorovať / foos a / bary vyššie definované definície zdrojov pomocou a typ zdroja zachytiť spoločné vlastnosti. Použijeme vyhradený parameter <>a užívateľom definovaný parameter <> reprezentovať použitý dátový typ.

5.1 Definícia

Tu je typ zdroja definícia predstavujúca kolekciu položiek:

resourceTypes: collection: usage: Použite tento resourceType na predstavenie ľubovoľnej zbierky položiek popis: Kolekcia <> get: description: Get all <>, voliteľne filtrované odpovede: 200: body: application / json: type: <> [] príspevok : description: Vytvoriť nové <> odpovede: 201: body: application / json: type: <>

Všimnite si, že v našom API, pretože naše dátové typy sú iba veľké, singulárne verzie názvov našich základných zdrojov, sme mohli použiť funkcie na <<resourcePathName>> namiesto zavedenia užívateľom definovaného <<typeName>> parameter, aby sa dosiahol rovnaký výsledok pre túto časť API:

resourcesTypes: collection: ... get: ... type: <> [] post: ... type: <>

5.2 Aplikácia

Použitím vyššie uvedenej definície, ktorá obsahuje znak <<typeName>> parameter, tu je príklad, ako by ste použili „kolekciu“ typ zdroja k zdrojom / foos a /tyče:

/ foos: type: {collection: {"typeName": "Foo"}} get: queryParameters: name ?: string ownerName ?: string ... / bars: type: {collection: {"typeName": "Bar"} }

Všimnite si, že stále dokážeme zakomponovať rozdiely medzi týmito dvoma zdrojmi - v tomto prípade queryParameters oddiel - zatiaľ čo stále využíva všetko, čo typ zdroja definícia ponúka.

6. Extrahovanie typu zdroja pre jednotlivé položky zbierky

Poďme sa teraz zamerať na časť nášho API, ktorá sa zaoberá jednotlivými položkami kolekcie: / foos / {fooId} a / bary / {barId} zdrojov. Tu je kód pre/ foos / {fooId}:

/ foos: ... / {fooId}: get: description: Získajte odpovede Foo: 200: body: application / json: type: Foo 404: body: application / json: type: Príklad chyby:! include examples / Error. json put: description: Update a Foo body: application / json: type: Foo response: 200: body: application / json: type: Foo 404: body: application / json: type: Error example:! include examples / Error.json delete: description: Delete a Foo responses: 204: 404: body: application / json: type: Error example:! include examples / Error.json

The / bary / {barId} definícia zdroja má tiež metódy GET, PUT a DELETE a je identická s /foos / {fooId} definícia, iná ako výskyty reťazcov „foo“ a „bar“ (a ich príslušné množné a / alebo veľké písmená).

6.1 Definícia

Extrahovaním vzoru, ktorý sme práve identifikovali, definujeme a typ zdroja pre jednotlivé položky zbierky:

resourceTypes: ... item: usage: Použite tento resourceType na vyjadrenie ľubovoľnej jednotlivej položky: Single <> get: description: Get a <> response: 200: body: application / json: type: <> 404: body: application / json: type: Príklad chyby:! include examples / Error.json put: description: Update a <> body: application / json: type: <> response: 200: body: application / json: type: <> 404: body : application / json: type: Príklad chyby:! include examples / Error.json delete: description: Delete a <> response: 204: 404: body: application / json: type: Error example:! include examples / Error.json

6.2 Aplikácia

A takto aplikujeme „položku“ typ zdroja:

/ foos: ... / {fooId}: type: {item: {"typeName": "Foo"}}
... / bars: ... / {barId}: type: {item: {"typeName": "Bar"}}

7. Rysy

Keďže a typ zdroja sa používa na extrakciu vzorov z definícií zdrojov, a vlastnosť sa používa na extrakciu vzorov z definícií metód, ktoré sú spoločné pre všetky zdroje.

7.1 Parametre

Spolu s <<resourcePath>> a <<resourcePathName>>, v definíciách znakov je k dispozícii jeden ďalší vyhradený parameter: <<methodName>> vyhodnotí na metódu HTTP (GET, POST, PUT, DELETE atď.), pre ktorú vlastnosť je definovaný. Užívateľom definované parametre sa môžu tiež objaviť v definícii znaku a ak sa použijú, prevezmú hodnotu prostriedku, v ktorom sa používajú.

7.2 Definícia

Všimnite si, že „položka“ typ zdroja je stále plný prepúšťania. Uvidíme ako črty môže pomôcť pri ich eliminácii. Začneme extrakciou a vlastnosť pre každú metódu obsahujúcu telo žiadosti:

vlastnosti: hasRequestItem: body: application / json: type: <>

Teraz poďme extrahovať črty pre metódy, ktorých normálne reakcie obsahujú orgány:

 hasResponseItem: response: 200: body: application / json: type: <> hasResponseCollection: response: 200: body: application / json: type: <> []

Nakoniec je tu a vlastnosť pre každú metódu, ktorá by mohla vrátiť chybovú odpoveď 404:

 hasNotFound: response: 404: body: application / json: type: Príklad chyby:! include examples / Error.json

7.3 Aplikácia

Toto potom aplikujeme vlastnosť k nášmu typy zdrojov:

resourceTypes: collection: usage: Použite tento resourceType na predstavenie ľubovoľnej zbierky položiek popis: Zbierka <> get: description: | Získať všetko <>, voliteľne filtrované je: [hasResponseCollection: {typeName: <>}] post: description: Create a new <> is: [hasRequestItem: {typeName: <>}] item: usage: Use this resourceType to represent any popis jednej položky: Jeden <> get: description: Get a <> is: [hasResponseItem: {typeName: <>}, hasNotFound] put: description: Update a <> is: | [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Delete a <> is: [hasNotFound] response: 204:

Môžeme sa aj prihlásiť črty metód definovaných v rámci zdrojov. To je obzvlášť užitočné pre „jednorazové“ scenáre, kde sa kombinácia prostriedkov a metód zhoduje s jedným alebo viacerými črty ale nezhoduje sa so žiadnym definovaným typ zdroja:

/ foos: ... / name / {name}: get: description: Zoznam všetkých foos s určitým menom je: [hasResponseCollection: {typeName: Foo}]

8. Záver

V tomto tutoriáli sme si ukázali, ako významne znížiť alebo v niektorých prípadoch vylúčiť redundancie z definície API RAML.

Najskôr sme identifikovali nadbytočné časti našich zdrojov, rozpoznali sme ich vzorce a extrahovali sme ich typy zdrojov. Potom sme urobili to isté pre metódy, ktoré boli bežné pri extrakcii zdrojov črty. Potom sme boli schopní eliminovať ďalšie prepúšťanie podaním žiadosti črty k nášmu typy zdrojov a na „jednorazové“ kombinácie zdrojov a metód, ktoré sa striktne nezhodovali s jednou z našich definovaných typy zdrojov.

Výsledkom bolo zníženie nášho jednoduchého API so zdrojmi iba pre dve entity zo 177 na niečo viac ako 100 riadkov kódu. Ak sa chcete dozvedieť viac informácií o RAML typy zdrojov a črty, navštívte stránku RAML.org 1.0 spec.

The úplná implementácia tohto tutoriálu nájdete v projekte github.

Toto je naše posledné úplné RAML API:

#% 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á žiadosť musí obsahovať hlavičky potrebné pre základný typ autentifikácie: Základné autentifikácia popísaná V: hlavičky: Autorizácia: popis: | Používa sa na odoslanie poverení typu "používateľské meno: heslo" s kódovaním Base64 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:! include types / Foo.raml Bar:! include types / Bar.raml Error:! include types / Error.raml resourceTypes: collection: usage: Use this resourceType to represent a collection of items description: A collection of < > získať: description: | Získať všetko <>, voliteľne filtrované je: [hasResponseCollection: {typeName: <>}] post: description: | Vytvorte nový <> je: [hasRequestItem: {typeName: <>}] položka: použitie: Použite tento resourceType na vyjadrenie ľubovoľného popisu jednej položky: Jeden <> get: description: Získajte <> je: [hasResponseItem: {typeName : <>}, hasNotFound] put: description: Update a <> is: [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Delete a <> is: [hasNotFound ] odpovede: 204: vlastnosti: hasRequestItem: body: application / json: type: <> hasResponseItem: response: 200: body: application / json: type: <> hasResponseCollection: response: 200: body: application / json: type: < > [] hasNotFound: response: 404: body: application / json: type: Príklad chyby:! include examples / Error.json / foos: type: {collection: {typeName: Foo}} get: queryParameters: name ?: string ownerName ?: string / {fooId}: type: {item: {typeName: Foo}} / name / {name}: get: description: Zoznam všetkých foos s určitým menom je: [hasResponseCollection: {typeName: Foo}] / bary : typ: {collecti on: {typeName: Bar}} / {barId}: type: {item: {typeName: Bar}} / fooId / {fooId}: get: description: Získajte všetky pruhy pre zodpovedajúci fooId je: [hasResponseCollection: {typeName: Bar}]
Ďalšie » Modulárna RAML pomocou inklúzií, knižníc, prekrytí a rozšírení « Predchádzajúci úvod do RAML - modelového jazyka RESTful API

Populárne Príspevky

Posledné príspevky

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