streamalism.org

Ez a cikk egy sorozat része: • Bevezetés a RAML-be - A RESTful API modellezési nyelv

• A redlundációk kiküszöbölése a RAML-ben erőforrástípusokkal és jellemzőkkel (aktuális cikk) • Moduláris RAML a Tartozékok, könyvtárak, átfedések és kiterjesztések használatával

• Definiálja az egyedi RAML tulajdonságokat a kommentárok segítségével

1. Áttekintés

RAML oktató cikkünkben bemutattuk a RESTful API modellezési nyelv és létrehozott egy egyszerű API definíciót egyetlen entitás alapján Foo. Most képzeljen el egy valós API-t, amelyben több entitástípusú erőforrással rendelkezik, amelyek mindegyike azonos vagy hasonló GET, POST, PUT és DELETE műveletekkel rendelkezik. Láthatja, hogyan válhat az API-dokumentáció gyorsan unalmassá és ismétlődővé.

Ebben a cikkben megmutatjuk, hogy a erőforrástípusok és vonások funkciók a RAML-ben kiküszöbölni a redundanciákat az erőforrások és a módszerek meghatározásában a közös szakaszok kibontásával és paraméterezésével, ezáltal kiküszöbölve a másolási és beillesztési hibákat, miközben az API-definíciók tömörebbé válnak.

2. API-junk

A. Előnyeinek bemutatása érdekében erőforrástípusok és vonások, kibővítjük az eredeti API-t azáltal, hogy hozzáadunk erőforrásokat egy második entitás típushoz, az ún Rúd. Itt találhatók a felülvizsgált API-t alkotó erőforrások:

• GET / api / v1 / foos
• POST / api / v1 / foos
• GET / api / v1 / foos / {fooId}
• PUT / api / v1 / foos / {fooId}
• TÖRLÉS / api / v1 / foos / {fooId}
• GET / api / v1 / foos / name / {név}
• GET / api / v1 / foos? Név = {név} & tulajdonosNév = {tulajdonosNév}
• GET / api / v1 / bárok
• POST / api / v1 / bárok
• GET / api / v1 / bárok / {barId}
• PUT / api / v1 / bárok / {barId}
• DELETE / api / v1 / bars / {barId}
• GET / api / v1 / bars / fooId / {fooId}

3. A minták felismerése

Ahogy végigolvassuk az erőforrások listáját az API-nkban, kezdjük látni, hogy néhány minta megjelenik. Például van egy minta az egyes entitások létrehozásához, olvasásához, frissítéséhez és törléséhez használt URI-khoz és módszerekhez, valamint van egy minta az entitások gyűjteményeinek visszahívásához használt URI-khoz és módszerekhez. A gyűjtés és a gyűjtemény-elem mintázata az egyik leggyakrabban használt mintázat erőforrástípusok a RAML definíciókban.

Nézzünk meg néhány API-t:

[Megjegyzés: Az alábbi kódrészletekben egy csak három pontot tartalmazó sor (…) azt jelzi, hogy néhány sort rövidség miatt kihagynak.]

/ foos: get: leírás: | Sorolja fel az összes lekérdezési feltételnek megfelelő csíkot, ha rendelkezésre áll; különben sorolja fel az összes foos lekérdezéstParaméterek: név ?: karakterlánc tulajdonosNév ?: karakterlánc-válaszok: 200: törzs: alkalmazás / json: típus: Foo [] bejegyzés: leírás: Hozzon létre új foo törzset: alkalmazás / json: típus: Foo válaszok: 201: body: application / json: type: Foo ... / bars: get: description: | Sorolja fel az összes sávot, amelyek megfelelnek a lekérdezési feltételeknek, ha rendelkezésre állnak; egyébként felsorolja az összes sávot lekérdezésParaméterek: név ?: karakterlánc tulajdonosNév ?: karakterlánc-válaszok: 200: törzs: alkalmazás / json: típus: Sáv [] bejegyzés: leírás: Új sávtörzs létrehozása: alkalmazás / json: típus: Sávválaszok: 201: test: alkalmazás / json: típus: Bár

Ha összehasonlítjuk a RAML definícióit / foos és / bárok erőforrások, beleértve az alkalmazott HTTP módszereket, mindegyik különféle tulajdonságai között több redundanciát tapasztalhatunk, és ismét látni kezdjük a minták kialakulását.

Ahol van minta az erőforrás vagy a módszer meghatározásában, lehetőség nyílik a RAML használatára erőforrás típusa vagy jellemvonás.

4. Erőforrás típusok

Az API-ban található minták megvalósítása érdekében erőforrástípusok használjon fenntartott és felhasználó által definiált paramétereket, dupla szögletes zárójelek (<>) körül.

4.1 Fenntartott paraméterek

Két fenntartott paraméter használható az erőforrás típus meghatározásában:

• <> képviseli a teljes URI-t (a baseURI), és
• <> az URI jobb szélső perjelet (/) követő részét jelöli, figyelmen kívül hagyva a zárójeleket {}.

Az erőforrás-definíción belüli feldolgozáskor az értékeik kiszámítása a definiált erőforrás alapján történik.

Adott az erőforrás / foos, például, <> értékelné, hogy „/ foos” és <>„foosnak” értékelné.

Adott az erőforrás / foos / {fooId}, <> értékeli a „/ foos / {fooId}” és <>„foosnak” értékelné.

4.2 Felhasználó által definiált paraméterek

A erőforrás típusa definíció tartalmazhat felhasználó által definiált paramétereket is. A fenntartott paraméterektől eltérően, amelyek értékeit dinamikusan határozzák meg a definiált erőforrás alapján, a felhasználó által definiált paraméterekhez hozzá kell rendelni értékeket, bárhol erőforrás típusa tartalmazza azokat, és ezek az értékek nem változnak.

A felhasználó által definiált paraméterek deklarálhatók az a elején erőforrás típusa definíció, bár erre nincs szükség és ez nem általános gyakorlat, mivel az olvasó általában meg tudja találni a rendeltetésszerű felhasználást, megadva a nevüket és a használatuk összefüggéseit.

4.3 Paraméterfunkciók

Egy maroknyi hasznos szöveges függvény áll rendelkezésre mindenütt, ahol egy paramétert használnak a paraméter kibővített értékének átalakításához, amikor azt egy erőforrás-meghatározásban feldolgozzák.

A paraméter-átalakításhoz elérhető funkciók:

• !szingularizálni
• !pluralizálni
• !nagybetűs
• !kisbetűs
• !felső kamra
• !alsó kamra
• !upperunderscorecase
• !alsó korszak
• !felső hyphencase
• !alsó tagozat

A függvényeket egy paraméterre a következő konstrukcióval alkalmazzák:

<<paraméterNév | !functionName>>

Ha egynél több függvényt kell használnia a kívánt transzformáció eléréséhez, akkor az egyes függvények nevét el kell választania a cső szimbólummal („|”), és minden egyes használt függvény előtt fel kell adnia egy felkiáltójelet (!).

Például, figyelembe véve az erőforrást / foos, ahol <<resourcePathName>> „foosnak” értékeli:

• <<resourcePathName | !szingularizálni>> ==> „foo”
• <<resourcePathName | !nagybetűs>> ==> „FOOS”
• <<resourcePathName | !szingularizálni | !nagybetűs>> ==> „FOO”

És adott az erőforrás / bars / {barId}, ahol <<resourcePathName>> „bar” -nak értékeli:

• <<resourcePathName | !nagybetűs>> ==> „BARS”
• <<resourcePathName | !felső kamra>> ==> „Bár”

5. Erőforrás-típus kinyerése a gyűjteményekhez

Refaktorozzuk a / foos és / bárok a fentiekben bemutatott erőforrás-meghatározások, a erőforrás típusa hogy megragadja a közös tulajdonságokat. A fenntartott paramétert fogjuk használni <>és a felhasználó által definiált paraméter <> a használt adattípus képviseletére.

5.1 Meghatározás

Itt van egy erőforrás típusa cikkgyűjteményt tartalmazó definíció:

resourceTypes: collection: use: Használja ezt az resourceType elemet az elemek bármelyik leírásának ábrázolására: <> get: description: Get all <> gyűjteménye, opcionálisan szűrt válaszok: 200: body: application / json: type: <> [] post : leírás: Hozzon létre új <> válaszokat: 201: body: application / json: type: <>

Vegye figyelembe, hogy az API-ban, mivel az adattípusaink csak nagybetűkkel írták, az alap erőforrásaink nevének egyes változatai, alkalmazhattunk volna függvényeket a <<resourcePathName>> paraméter, a felhasználó által definiált << bevezetése helyetttypeName>> paraméter, ugyanazon eredmény elérése érdekében az API ezen részén:

resourceTypes: gyűjtemény: ... get: ... type: <> [] post: ... type: <>

5.2 Alkalmazás

A fenti definícióval, amely magában foglalja a << elemettypeName>> paraméter, itt állíthatja be a „gyűjtemény” alkalmazását erőforrás típusa az erőforrásokhoz / foos és /bárok:

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

Figyeljük meg, hogy továbbra is képesek vagyunk beépíteni a két erőforrás - ebben az esetben a queryParameters szakasz - miközben továbbra is kihasználja mindazt, amit a erőforrás típusa meghatározása kínálhat.

6. Erőforrás-típus kinyerése a gyűjtemény egyes tételeihez

Most összpontosítsunk API-nknak arra a részére, amely a gyűjtemény egyes elemeivel foglalkozik: a / foos / {fooId} és / bars / {barId} erőforrások. Itt van a/ foos / {fooId}:

/ foos: ... / {fooId}: get: description: Kérjen egy Foo válaszokat: 200: body: application / json: type: Foo 404: body: application / json: type: Error example:! include példák / Error. json put: leírás: Frissítsen egy Foo törzset: application / json: type: Foo válaszok: 200: body: application / json: type: Foo 404: body: application / json: type: Hiba példa:! include példák / Error.json delete: leírás: Foo válaszok törlése: 204: 404: body: application / json: type: Hiba példa:! include példák / Error.json

A / bars / {barId} az erőforrás-meghatározás GET, PUT és DELETE metódusokkal is rendelkezik, és megegyezik a /foos / {fooId} meghatározás, kivéve a „foo” és „bar” karakterláncok előfordulását (és azok megfelelő pluralizált és / vagy nagybetűs formáit).

6.1 Meghatározás

Kivonva az imént azonosított mintát, itt határozhatjuk meg a erőforrás típusa a gyűjtemény egyes tételeihez:

resourceTypes: ... item: use: Használja ezt az resourceType elemet bármely elem leírásának ábrázolására: Egyetlen <> get: description: Válaszok beolvasása: 200: body: application / json: type: <> 404: body: application / json: type: Hiba példa:! include példák / Error.json put: description: Frissítsen egy <> body: application / json: type: <> válaszokat: 200: body: application / json: type: <> 404: body : application / json: type: Hibapélda:! include példák / Error.json delete: description: <> válaszok törlése: 204: 404: body: application / json: type: Hibapélda:! include példák / Error.json

6.2 Alkalmazás

És itt van, hogyan alkalmazzuk az „elemet” erőforrás típusa:

/ foos: ... / {fooId}: típus: {item: {"typeName": "Foo"}}

... / bárok: ... / {barId}: típus: {item: {"typeName": "Bar"}}

7. vonások

Mivel a erőforrás típusa az erőforrás-meghatározások mintáinak kinyerésére szolgál, a jellemvonás arra szolgál, hogy az erőforrásokon általános metódusokat nyerje ki a módszer definícióiból.

7.1 Paraméterek

A << mellettresourcePath>> és <<resourcePathName>>, egy további fenntartott paraméter áll rendelkezésre a tulajdonságok meghatározásában: <<methodName>> kiértékeli azt a HTTP metódust (GET, POST, PUT, DELETE stb.), amelyhez a jellemvonás meg van határozva. A felhasználó által definiált paraméterek megjelenhetnek egy tulajdonság definíción belül is, és ha alkalmazzák, vegyék fel az erőforrás értékét, amelyben alkalmazzák őket.

7.2 Meghatározás

Figyelje meg, hogy az „elem” erőforrás típusa még mindig tele van elbocsátásokkal. Lássuk, hogyan vonások segíthet megszüntetni őket. Kezdjük a jellemvonás bármely olyan eljárás esetében, amely egy kérő testületet tartalmaz:

vonások: hasRequestItem: body: application / json: type: <>

Most vonjuk ki vonások olyan módszerek esetében, amelyek normál válaszai testeket tartalmaznak:

 hasResponseItem: válaszok: 200: body: application / json: type: <> hasResponseCollection: válaszok: 200: body: application / json: type: <> []

Végül itt van a jellemvonás minden olyan módszer esetében, amely 404-es hibaüzenetet adhat vissza:

 hasNotFound: válaszok: 404: body: application / json: type: Hibapélda:! include példák / Error.json

7.3 Alkalmazás

Ezután ezt alkalmazzuk jellemvonás a miénknek erőforrástípusok:

resourceTypes: collection: use: Használja ezt az resourceType elemet bármely elemgyűjtemény leírásához: A <> get: description: | Az összes beszerzése <>, opcionálisan szűrve: [hasResponseCollection: {typeName: <>}] post: description: Hozzon létre egy új <> is: [hasRequestItem: {typeName: <>}] elem: use: Használja ezt az resourceType-t bármelyik képviseletére egyetlen elem leírása: Egyetlen <> get: description: Get a <> is: [hasResponseItem: {typeName: <>}, hasNotFound] put: description: Frissítsen egy <> is: | [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Töröljön egy <> is: [hasNotFound] választ: 204:

Jelentkezhetünk is vonások az erőforrásokban meghatározott módszerekhez. Ez különösen hasznos az „egyszeri” forgatókönyveknél, amikor az erőforrás-módszer kombináció egy vagy több egyezik vonások de nem felel meg egyetlen meghatározottnak sem erőforrás típusa:

/ foos: ... / név / {név}: get: leírás: Az összes, bizonyos névvel rendelkező csempe felsorolása: [hasResponseCollection: {typeName: Foo}]

8. Következtetés

Ebben az oktatóanyagban bemutattuk, hogyan lehet jelentősen csökkenteni vagy egyes esetekben megszüntetni a redundanciákat a RAML API-definícióból.

Először azonosítottuk erőforrásaink felesleges szakaszait, felismertük azok mintázatát és kivontuk erőforrástípusok. Aztán ugyanezt tettük az erőforrásokban közös kivonatolási módszerekkel vonások. Ezután jelentkezéssel kiküszöbölhettük a további elbocsátásokat vonások a miénknek erőforrástípusok valamint „egyszeri” erőforrás-módszer kombinációkra, amelyek nem egyeztek szigorúan a definiáltakkal erőforrástípusok.

Ennek eredményeként a csak két entitás erőforrásaival rendelkező egyszerű API-junk 177-ről alig több mint 100 soros kódra csökkent. Ha többet szeretne megtudni a RAML-ről erőforrástípusok és vonások, keresse fel a RAML.org 1.0 specifikációt.

A teljes végrehajtása a bemutató a github projektben található.

Itt van a végső RAML API teljes egészében:

#% RAML 1.0 title: Baeldung Foo REST Services API version: v1 protokols: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application / json securedBy: basicAuth securitySchemes: basicAuth: description: | Minden kérelemnek tartalmaznia kell az alapvető hitelesítési típushoz szükséges fejléceket: A leírt alapvető hitelesítésBy: fejlécek: Engedélyezés: leírás: | A Base64 kódolású "felhasználónév: jelszó" hitelesítő adatok küldéséhez használt: string válaszok: 401: leírás: | Jogosulatlan. Vagy a megadott felhasználónév és jelszó kombináció érvénytelen, vagy a felhasználó nem férhet hozzá a kért URL által biztosított tartalomhoz. type: Foo:! include types / Foo.raml Bar:! include types / Bar.raml Error:! include types / Error.raml resourceTypes: collection: use: Használja ezt az resourceType elemcsoportot a leíráshoz: < > get: leírás: | Az összes beolvasása <>, opcionálisan szűrt: [hasResponseCollection: {typeName: <>}] post: description: | Hozzon létre egy új <> is: [hasRequestItem: {typeName: <>}] elem: use: Használja ezt az resourceType elemet egyetlen tétel leírásának ábrázolására: Egyetlen <> get: description: Get a <> is: [hasResponseItem: {typeName : <>}, hasNotFound] put: description: Frissítsen egy <> -t: [hasRequestItem: {typeName: <>}, hasResponseItem: {typeName: <>}, hasNotFound] delete: description: Töröljön egy <> is: [hasNotFound ] válaszok: 204: tulajdonságok: hasRequestItem: body: application / json: type: <> hasResponseItem: válaszok: 200: body: application / json: type: <> hasResponseCollection: válaszok: 200: body: application / json: type: < > [] hasNotFound: válaszok: 404: body: application / json: type: Hibapélda:! include példák / Error.json / foos: type: {gyűjtemény: {typeName: Foo}} get: queryParameters: név ?: string tulajdonosNév ?: string / {fooId}: type: {item: {typeName: Foo}} / name / {name}: get: description: Az összes, bizonyos névvel rendelkező csempe felsorolása: [hasResponseCollection: {typeName: Foo}] / bárok : típus: {collecti on: {typeName: Bar}} / {barId}: type: {item: {typeName: Bar}} / fooId / {fooId}: get: description: Az összes sáv beszerzése a megfelelő fooId-hez: [hasResponseCollection: {typeName: Rúd } ]

Következő » Moduláris RAML a Tartalom, könyvtárak, átfedések és kiterjesztések használatával « Korábbi bevezetés a RAML-be - A RESTful API modellezési nyelv