Uklonite viškove u RAML-u pomoću vrsta i osobina resursa

Ovaj je članak dio serije: • Uvod u RAML - RESTful API Modeling Language

• Uklonite viškove u RAML-u s vrstama resursa i osobinama (trenutni članak) • Modularni RAML koji koristi uključuje, knjižnice, prekrivače i proširenja

• Definirajte prilagođena svojstva RAML-a pomoću bilješki

1. Pregled

U našem udžbeničkom članku o RAML-u predstavili smo RESTful API jezik za modeliranje i stvorili jednostavnu definiciju API-ja temeljenu na jednom entitetu zvanom Foo. Sada zamislite API iz stvarnog svijeta u kojem imate nekoliko resursa entiteta, svi koji imaju iste ili slične GET, POST, PUT i DELETE operacije. Možete vidjeti kako vaša API dokumentacija može brzo postati zamorna i ponavljana.

U ovom članku prikazujemo kako se koristi vrste resursa i osobine značajke u RAML-u mogu eliminirati višak u definicijama resursa i metoda izdvajanjem i parametriziranjem uobičajenih odjeljaka, uklanjajući na taj način pogreške kopiranja i lijepljenja, dok vaše definicije API-ja postaju sažetije.

2. Naš API

Kako bi se demonstrirale prednosti vrste resursa i osobine, proširit ćemo svoj izvorni API dodavanjem resursa za drugu vrstu entiteta pod nazivom Bar. Evo resursa koji će činiti naš revidirani API:

  • GET / api / v1 / foos
  • POST / api / v1 / foos
  • GET / api / v1 / foos / {fooId}
  • PUT / api / v1 / foos / {fooId}
  • IZBRIŠI / api / v1 / foos / {fooId}
  • GET / api / v1 / foos / name / {name}
  • GET / api / v1 / foos? Name = {name} & ownerName = {ownerName}
  • GET / api / v1 / barovi
  • POST / api / v1 / barovi
  • GET / api / v1 / barovi / {barId}
  • PUT / api / v1 / barovi / {barId}
  • IZBRIŠI / api / v1 / bars / {barId}
  • GET / api / v1 / bars / fooId / {fooId}

3. Prepoznavanje obrazaca

Čitajući popis resursa u našem API-ju, počinjemo vidjeti kako se pojavljuju neki obrasci. Na primjer, postoji obrazac za URI-je i metode korištene za stvaranje, čitanje, ažuriranje i brisanje pojedinačnih entiteta, a postoji i obrazac za URI-je i metode korištene za dohvaćanje zbirki entiteta. Uzorak zbirke i predmeta predmeta sakupljanja jedan je od najčešćih uzoraka koji se koriste za izdvajanje vrste resursa u RAML definicijama.

Pogledajmo nekoliko odjeljaka našeg API-ja:

[Napomena: U isječcima koda u nastavku redak koji sadrži samo tri točke (...) označava da se neki redovi preskaču zbog kratkoće.]

/ foos: get: description: | Navedite sve foos koji odgovaraju kriterijima upita, ako su navedeni; u suprotnom navesti sve foos queryParameters: name ?: string ownerName ?: string odgovori: 200: body: application / json: type: Foo [] post: description: Create a new foo body: application / json: type: Foo response: 201: body: application / json: type: Foo ... / bars: get: description: | Navedite sve trake koje odgovaraju kriterijima upita, ako su navedeni; u suprotnom navesti sve trake queryParameters: name ?: string ownerName ?: string odgovori: 200: body: application / json: type: Bar [] post: description: Create a new body body: application / json: type: Bar response: 201: body: application / json: type: Bar

Kada usporedimo RAML definicije / foos i /barovi resursa, uključujući korištene HTTP metode, možemo vidjeti nekoliko suvišnosti među različitim svojstvima svake od njih, a opet vidimo kako se obrasci počinju pojavljivati.

Gdje god postoji obrazac bilo u definiciji resursa ili metode, postoji mogućnost korištenja RAML-a vrsta resursa ili osobina.

4. Vrste resursa

Da bi se implementirali obrasci pronađeni u API-ju, vrste resursa koristite rezervirane i korisnički definirane parametre okružene dvokutnim zagradama (<>).

4.1 Rezervirani parametri

U definicijama vrsta resursa mogu se koristiti dva rezervirana parametra:

  • <> predstavlja cijeli URI (slijedeći baseURI) i
  • <> predstavlja dio URI-a koji slijedi kočnicu naprijed udesno (/), zanemarujući sve zagrade {}.

Kada se obrade unutar definicije resursa, njihove vrijednosti izračunavaju se na temelju resursa koji se definira.

S obzirom na resurs / foos, na primjer, <> bi procijenio na "/ foos" i <>bi procijenio na "foos".

S obzirom na resurs / foos / {fooId}, <> bi procijenio na "/ foos / {fooId}" i <>bi procijenio na "foos".

4.2 Korisnički definirani parametri

A vrsta resursa definicija može sadržavati i korisnički definirane parametre. Za razliku od rezerviranih parametara, čije se vrijednosti dinamički određuju na temelju resursa koji se definira, korisnički definiranim parametrima moraju se dodijeliti vrijednosti gdje god vrsta resursa koristi se njihov sadržaj koji se ne mijenja.

Korisnički definirani parametri mogu se prijaviti na početku a vrsta resursa definicija, iako to nije potrebno i nije uobičajena praksa, jer čitatelj obično može shvatiti namjeravanu uporabu s obzirom na njihova imena i kontekst u kojem se koriste.

4.3 Parametarske funkcije

Pregršt korisnih tekstualnih funkcija dostupno je za uporabu svugdje gdje se parametar koristi za transformiranje proširene vrijednosti parametra kada se obrađuje u definiciji resursa.

Evo funkcija dostupnih za transformaciju parametara:

  • !singularizirati
  • !pluralizirati
  • !velikim slovima
  • !malim slovima
  • !gornja kamela
  • !donji kamenac
  • !upperunderscorecase
  • !donji donji znak
  • !gornji crtica
  • !donji crtica

Funkcije se primjenjuju na parametar pomoću sljedeće konstrukcije:

<<parametarName | !functionName>>

Ako trebate koristiti više od jedne funkcije da biste postigli željenu transformaciju, razdvojili biste ime svake funkcije znakom cijevi ("|") i dodali uskličnik (!) Prije svake korištene funkcije.

Na primjer, s obzirom na resurs / foos, gdje <<resourcePathName>> procjenjuje na "foos":

  • <<resourcePathName | !singularizirati>> ==> "foo"
  • <<resourcePathName | !velikim slovima>> ==> “FOOS”
  • <<resourcePathName | !singularizirati | !velikim slovima>> ==> "FOO"

A s obzirom na resurs / barovi / {barId}, gdje <<resourcePathName>> ocjenjuje u "barove":

  • <<resourcePathName | !velikim slovima>> ==> “ŠIPKE”
  • <<resourcePathName | !gornja kamela>> ==> "Bar"

5. Izdvajanje vrste resursa za zbirke

Preoblikujmo / foos i /barovi definicije resursa prikazane gore, koristeći a vrsta resursa da uhvati zajednička svojstva. Upotrijebit ćemo rezervirani parametar <>i korisnički definirani parametar <> za predstavljanje vrste podataka koja se koristi.

5.1 Definicija

Ovdje je vrsta resursa definicija koja predstavlja kolekciju predmeta:

resourceTypes: collection: usage: Koristite ovaj resourceType za predstavljanje bilo koje kolekcije opisa predmeta: Zbirka <> get: description: Dobiti sve <>, po želji filtrirani odgovori: 200: body: application / json: type: <> [] post : description: Stvorite nove <> odgovore: 201: body: application / json: type: <>

Imajte na umu da smo u našem API-ju, jer su naše vrste podataka samo velike početne vrijednosti, pojedinačne verzije imena naših osnovnih resursa, mogli primijeniti funkcije na <<resourcePathName>> parametar, umjesto uvođenja korisnički definiranog <<typeName>> parametar, za postizanje istog rezultata za ovaj dio API-ja:

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

5.2 Primjena

Koristeći gornju definiciju koja uključuje <<typeName>> parametar, evo kako biste primijenili “zbirku” vrsta resursa resursima / foos i /barovi:

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

Primijetite da još uvijek možemo uključiti razlike između dva resursa - u ovom slučaju, queryParameters odjeljak - dok još uvijek iskorištavate sve ono što vrsta resursa definicija koja nudi.

6. Izdvajanje vrste resursa za pojedinačne predmete zbirke

Usredotočimo se sada na dio našeg API-ja koji se bavi pojedinačnim predmetima kolekcije: / foos / {fooId} i / barovi / {barId} resursi. Evo šifre za/ foos / {fooId}:

/ foos: ... / {fooId}: get: description: Dobijte odgovore Foo-a: 200: body: application / json: type: Foo 404: body: application / json: type: Primjer pogreške:! uključuju primjere / pogrešku. json put: opis: Ažurirajte tijelo Foo-a: application / json: type: Foo odgovori: 200: body: application / json: type: Foo 404: body: application / json: type: Primjer pogreške:! uključuju primjere / Error.json delete: description: Delete a Foo odgovori: 204: 404: body: application / json: type: Primjer pogreške:! include examples / Error.json

The / barovi / {barId} Definicija resursa također ima metode GET, PUT i DELETE i identična je /foos / {fooId} definicija, osim pojava nizova "foo" i "bar" (i njihovih odgovarajućih pluraliziranih i / ili velikih slova).

6.1 Definicija

Izdvajanje uzorka koji smo upravo identificirali, evo kako definiramo a vrsta resursa za pojedinačne predmete kolekcije:

resourceTypes: ... item: usage: Koristite ovaj resourceType za predstavljanje bilo kojeg opisa pojedinačne stavke: Jedan <> get: description: Get a <> response: 200: body: application / json: type: <> 404: body: application / json: type: Primjer pogreške:! uključuju primjere / Error.json put: description: Ažuriranje <> tijela: application / json: type: <> odgovora: 200: body: application / json: type: <> 404: body : application / json: type: Primjer pogreške:! include examples / Error.json delete: description: Delete a <> response: 204: 404: body: application / json: type: Primjer pogreške:! include examples / Error.json

6.2 Primjena

I evo kako primjenjujemo "stavku" vrsta resursa:

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

7. Osobine

Dok a vrsta resursa koristi se za izdvajanje uzoraka iz definicija resursa, a osobina koristi se za izdvajanje uzoraka iz definicija metoda koje su uobičajene u resursima.

7.1 Parametri

Uz <<resourcePath>> i <<resourcePathName>>, jedan dodatni rezervirani parametar dostupan je za upotrebu u definicijama osobina: <<methodName>> procjenjuje na HTTP metodu (GET, POST, PUT, DELETE, itd.) za koju osobina je definirano. Korisnički definirani parametri mogu se pojaviti i unutar definicije osobine, a tamo gdje su primijenjeni, poprimaju vrijednost resursa u kojem se primjenjuju.

7.2 Definicija

Primijetite da je "stavka" vrsta resursa je i dalje pun viškova. Da vidimo kako osobine može pomoći u njihovom uklanjanju. Započet ćemo izdvajanjem a osobina za bilo koju metodu koja sadrži tijelo zahtjeva:

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

Sad izvucimo osobine za metode čiji normalni odgovori sadrže tijela:

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

Napokon, evo a osobina za bilo koju metodu koja može vratiti odgovor na pogrešku 404:

 hasNotFound: odgovori: 404: tijelo: aplikacija / json: tip: Primjer pogreške:! uključuju primjere / Error.json

7.3 Primjena

Zatim primjenjujemo ovo osobina našem vrste resursa:

resourceTypes: collection: use: Koristite ovaj resourceType za predstavljanje bilo koje zbirke opisa predmeta: Zbirka <> get: description: | Dohvati sve <>, po želji filtrirano je: [hasResponseCollection: {typeName: <>}] post: description: Stvori novu <> je: [hasRequestItem: {typeName: <>}] stavka: upotreba: Koristite ovaj resursType za predstavljanje bilo kojeg opis jedne stavke: Jedan <> get: description: Get a <> je: [hasResponseItem: {typeName: <>}, hasNotFound] put: description: Update a <> is: | [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Delete a <> is: [hasNotFound] odgovori: 204:

Također se možemo prijaviti osobine metodama definiranim unutar resursa. To je posebno korisno za "jednokratne" scenarije u kojima se kombinacija resursa i metode podudara s jednim ili više osobine ali ne odgovara nijednom definiranom vrsta resursa:

/ foos: ... / name / {name}: get: description: Popis svih foosa s određenim imenom je: [hasResponseCollection: {typeName: Foo}]

8. Zaključak

U ovom smo uputstvu pokazali kako značajno smanjiti ili, u nekim slučajevima, eliminirati viškove iz definicije RAML API-ja.

Prvo smo identificirali suvišne dijelove naših resursa, prepoznali njihove obrasce i izdvojili ih vrste resursa. Zatim smo učinili isto za metode koje su uobičajene za izdvajanje osobine. Tada smo prijavom mogli eliminirati daljnje viškove osobine našem vrste resursa i na „jednokratne“ kombinacije metoda i resursa koje se nisu strogo podudarale s jednom od naših definiranih vrste resursa.

Kao rezultat toga, naš jednostavni API s resursima za samo dva entiteta smanjen je sa 177 na nešto više od 100 redaka koda. Da biste saznali više o RAML-u vrste resursa i osobine, posjetite RAML.org 1.0 specifikacije.

The puna provedba ovog vodiča možete pronaći u projektu github.

Evo našeg završnog RAML API-ja u cijelosti:

#% RAML 1.0 naslov: Baeldung Foo REST Services API verzija: v1 protokoli: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application / json securedBy: basicAuth securitySchemes: basicAuth: description: | Svaki zahtjev mora sadržavati zaglavlja potrebna za osnovni tip provjere autentičnosti: Osnovna opisana provjera autentičnostiBy: zaglavlja: Ovlaštenje: opis: | Koristi se za slanje vjerodajnica kodiranih Base64 "korisničko ime: lozinka" vrsta: nizovi odgovori: 401: opis: | Neovlašteno. Ili je navedena kombinacija korisničkog imena i lozinke nevaljana ili korisnik ne smije pristupiti sadržaju koji pruža traženi URL. tipovi: Foo:! uključuju tipove / Foo.raml Bar:! uključuju tipove / Bar.raml Greška:! uključuju tipove / Error.raml resourceTypes: collection: usage: Koristite ovaj resourceType za predstavljanje zbirke opisa predmeta: Zbirka < > dobiti: opis: | Dohvati sve <>, po želji filtrirano je: [hasResponseCollection: {typeName: <>}] post: description: | Stvaranje nove stavke <> je: [hasRequestItem: {typeName: <>}]: upotreba: Koristite ovaj resourceType za predstavljanje bilo kojeg opisa pojedine stavke: Jedan <> get: description: Nabavite <> je: [hasResponseItem: {typeName : <>}, hasNotFound] put: description: Ažuriranje <> je: [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Delete a <> is: [hasNotFound ] odgovori: 204: osobine: hasRequestItem: tijelo: aplikacija / json: tip: <> hasResponseItem: odgovori: 200: tijelo: aplikacija / json: tip: <> imaResponseCollection: odgovori: 200: tijelo: aplikacija / json: tip: < > [] hasNotFound: responses: 404: body: application / json: type: Primjer pogreške:! include examples / Error.json / foos: type: {collection: {typeName: Foo}} get: queryParameters: name ?: string ownerName ?: string / {fooId}: type: {item: {typeName: Foo}} / name / {name}: get: description: Popis svih foo-a s određenim imenom je: [hasResponseCollection: {typeName: Foo}] / bars : type: {collecti na: {typeName: Bar}} / {barId}: type: {item: {typeName: Bar}} / fooId / {fooId}: get: description: Nabavite sve trake za odgovarajući fooId je: [hasResponseCollection: {typeName: Traka}]
Sljedeći » Modularno korištenje RAML-a uključuje, knjižnice, slojeve i proširenja « Prethodni uvod u RAML - RESTful API Modeling Language

Popularni Postovi

Najnoviji postovi

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