Bevezetés a RAML-be - A RESTful API modellezési nyelv

Ez a cikk egy sorozat része: • Bevezetés a RAML-be - A RESTful API modellezési nyelv (aktuális cikk) • Megszünteti a redundanciákat a RAML-ben erőforrástípusokkal és tulajdonságokkal

• 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

Ebben a cikkben bemutatjuk a RESTful API modellezési nyelvet (RAML), a gyártótól semleges, nyílt specifikációjú nyelvet, amely a YAML 1.2-re és a JSON-ra épül a RESTful API-k leírására.

Kitérünk az alapvető RAML 1.0 szintaxisra és fájlstruktúrára, amikor bemutatjuk, hogyan definiálható egy egyszerű JSON-alapú API. Megmutatjuk azt is, hogyan egyszerűsítheti a RAML fájlok karbantartását a magába foglalja. És ha van olyan régi API-ja, amely JSON-sémát használ, akkor megmutatjuk, hogyan kell beépíteni a sémákat a RAML-be.

Ezután bemutatunk egy maroknyi eszközt, amelyek javíthatják az utazást a RAML-be, ideértve a szerzői eszközöket, a dokumentációgenerátorokat és másokat.

Végül összefoglaljuk a RAML specifikáció aktuális állapotának leírását.

2. Az API meghatározása (az. Létrehozása .raml fájl)

Az általunk definiált API meglehetősen egyszerű: az entitástípusokat figyelembe véve Foo, definiálja az alapvető CRUD műveleteket és pár lekérdezési műveletet. Itt vannak az erőforrások, amelyeket meghatározunk az API-hoz:

  • GET / api / v1 / foos
  • POST / api / v1 / foos
  • GET / api / v1 / foos / {id}
  • PUT / api / v1 / foos / {id}
  • TÖRLÉS / api / v1 / foos / {id}
  • GET / api / v1 / foos / name / {név}
  • GET / api / v1 / foos? Név = {név} & tulajdonosNév = {tulajdonosNév}

Határozzuk meg az API-t, hogy hontalan legyen, a HTTP Basic hitelesítést használja, és hogy titkosítva jelenjen meg HTTPS-en keresztül. Végül válasszuk a JSON-t az adatátviteli formátumunkhoz (az XML is támogatott).

2.1. Gyökérszintű beállítások

Kezdjük egy egyszerű szöveges fájl létrehozásával api.raml (a .raml előtag ajánlott; a név tetszőleges), és adja hozzá a RAML verzió fejlécét az első sorhoz. A fájl gyökérszintjén meghatározzuk a teljes API-ra vonatkozó beállításokat:

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

A 3. sorban vegye figyelembe a zárójelek használatát {} a „változat“. Így mondjuk a RAML-nek, hogy „változat" tulajdonságra vonatkozik, és bővíteni kell. Ezért a tényleges baseUri lesz: //myapi.mysite.com/v1

[Megjegyzés: a változat tulajdonság nem kötelező, és nem kell, hogy része legyen a baseUri.]

2.2. Biztonság

A biztonságot a .raml fájl. Tehát adjuk hozzá a HTTP alapbiztonsági séma definíciónkat:

securitySchemes: basicAuth: leírás: Minden kérelemnek tartalmaznia kell az alapvető hitelesítési típushoz szükséges fejléceket: Az alap hitelesítés leírtBy: fejlécek: Engedélyezés: leírás: A Base64 kódolású "felhasználónév: jelszó" hitelesítő adatok elküldéséhez: 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.

2.3. Adattípusok

Ezután meghatározzuk az adattípusokat, amelyeket API-nk használni fog:

típusok: Foo: type: objektum tulajdonságai: id: kötelező: true type: egész név: kötelező: true type: karakterlánc tulajdonosNév: kötelező: hamis típus: karakterlánc

A fenti példa kibővített szintaxist használ az adattípusaink meghatározásához. A RAML néhány szintaktikai parancsikont biztosít a típusdefiníciók kevésbé bőbeszédűvé tételéhez. Itt található az egyenértékű adattípusok szakasz, amely a következő parancsikonokat használja:

típusok: Foo: tulajdonságok: id: egész név: karakterlánc tulajdonosNév ?: karakterlánc Hiba: tulajdonságok: kód: egész üzenet: karakterlánc

A '?' a tulajdonság nevét követő karakter kijelenti, hogy a tulajdonság nem szükséges.

2.4. Erőforrások

Most meghatározzuk az API legfelső szintű erőforrását (URI):

/ foos:

2.5. URI paraméterek

Ezután kibővítjük az erőforrások listáját, a legfelső szintű erőforrásból építve:

/ foos: / {id}: / név / {név}: 

Itt a tulajdonságnevek körüli zárójelek {} meghatározzák az URI paramétereket. Az egyes URI-kben helyőrzőket képviselnek, és nem hivatkoznak a root szintű RAML fájl tulajdonságaira, amint azt fentebb láttuk a baseUri nyilatkozat. A hozzáadott sorok az erőforrásokat jelentik / foos / {id} és / foos / név / {név}.

2.6. Mód

A következő lépés az egyes erőforrásokra vonatkozó HTTP-módszerek meghatározása:

/ foos: get: post: / {id}: get: put: delete: / név / {név}: get:

2.7. Lekérdezési paraméterek

Most meghatározzuk a lekérdezés módját foos gyűjtemény lekérdezési paraméterekkel. Ne feledje, hogy a lekérdezési paramétereket ugyanazzal a szintaxissal határozzuk meg, amelyet fentebb használtunk az adattípusoknál:

/ foos: get: description: Sorolja fel az összes Foos keresési feltételnek megfelelő feltételt, ha rendelkezésre áll; különben sorolja fel az összes Foos queryParameters-t: név ?: karakterlánc tulajdonosNév ?: karakterlánc

2.8. Válaszok

Most, hogy meghatároztuk az API összes erőforrását, beleértve az URI paramétereket, a HTTP módszereket és a lekérdezési paramétereket, itt az ideje meghatározni a várható válaszokat és állapotkódokat. A válaszformátumokat általában az adattípusok és példák alapján határozzák meg.

A JSON séma adattípusok helyett használható a RAML korábbi verzióival való visszafelé való kompatibilitás érdekében. A JSON sémát a 3. szakaszban mutatjuk be.

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

Kezdjük az egyszerű GET művelettel / foos / {id}:

/ foos: ... / {id}: get: description: Foo megszerzése id válaszokkal: 200: body: application / json: type: Foo example: {"id": 1, "name": "First Foo" } 

Ez a példa azt mutatja, hogy GET kérést hajt végre az erőforráson / foos / {id}, vissza kellene kapnunk az egyezést Foo JSON objektum és 200 HTTP állapotkód formájában.

Így definiálhatjuk a GET kérést a / foos forrás:

/ foos: get: description: Sorolja fel az összes Foos megfelelő lekérdezési feltételt, 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 [] példa: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}] 

Vegye figyelembe a szögletes zárójelek használatát [] Foo típus. Ez bemutatja, hogyan definiálnánk egy válasz testet, amely egy tömböt tartalmaz Foo objektumok, a példa JSON objektumok tömbje.

2.9. Kérelem Test

Ezután meghatározzuk azokat a kéréstesteket, amelyek megfelelnek az egyes POST és PUT kéréseknek. Kezdjük egy új létrehozásával Foo tárgy:

/ foos: ... post: description: Hozzon létre egy új Foo törzset: application / json: type: Foo példa: {"id": 5, "name": "Another foo"} válaszok: 201: body: application / json : type: Foo example: {"id": 5, "name": "Another foo"} 

2.10. Állapotkódok

A fenti példában vegye figyelembe, hogy egy új objektum létrehozásakor 201-es HTTP-állapotot adunk vissza. Az objektum frissítésének PUT-művelete 200-as HTTP-állapotot ad vissza, ugyanazokat a kérelem- és választesteket felhasználva, mint a POST-művelet.

A várható válaszok és állapotkódok mellett, amelyeket egy kérés sikeres visszaküldése esetén adunk vissza, meghatározhatjuk a válasz fajtáját és egy állapotkódot, amelyre számíthatunk hiba esetén.

Lássuk, hogyan definiálnánk a GET-kérelem várható válaszát a / foos / {id} erőforrás, ha a megadott azonosítóval nem található erőforrás:

 404: body: application / json: type: Hiba példa: {"message": "Not found", "code": 1001} 

3. RAML JSON sémával

Előtt adattípusok a RAML 1.0-ban vezették be, az objektumokat, a kérelem testeket és a válasz testeket a JSON séma segítségével definiálták.

Használata adattípusok nagyon nagy teljesítményű lehet, de vannak esetek, amikor mégis használni szeretné a JSON sémát. A RAML 0.8-ban definiálta a sémákat a gyökérszint használatával sémák szakasz.

Ez még mindig érvényes, de ajánlott a típusok szakasz helyett sémák egy jövőbeli verzióban elavulhat. Mindkét típusok és sémák, továbbá típus és séma, szinonimák.

Így határozhatja meg a Foo objektumtípust a .raml fájl JSON séma használatával:

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

És itt van, hogyan hivatkozhat a sémára a GET-ben / foos / {id} erőforrás-meghatározás:

/ foos: ... / {id}: get: description: Szerezzen be egy Foo-t az id válaszai alapján: 200: body: application / json: type: foo ...

4. Refactoring With tartalmazza

Amint a fenti szakaszokból láthatjuk, az API-nk meglehetősen bőbeszédű és ismétlődő.

A RAML specifikáció tartalmaz egy beépítési mechanizmust, amely lehetővé teszi számunkra az ismétlődő és hosszú kódrészek külsővé tételét.

Átdolgozhatjuk az API definíciónkat az include használatával, így tömörebbé tehetjük, és kevésbé valószínű, hogy tartalmazza azokat a hibatípusokat, amelyek a „másolás / beillesztés / javítás mindenhol” módszertanból erednek.

Például feltehetjük az a adattípust Foo objektum a fájlban típusok / Foo.raml és az an típusa Hiba objektum be típusok / Error.raml. Akkor a mi típusok szakasz így néz ki:

típusok: Foo:! include types / Foo.raml Hiba:! include types / Error.raml

És ha helyette JSON sémát használunk, akkor a típusok szakasz így nézhet ki:

típusok: foo:! include sémák / foo.json hiba:! include sémák / error.json

5. Az API kitöltése

Miután az összes adattípust és példát külsõvé tettük a fájljaikba, átalakíthatjuk az API-t az include szolgáltatás segítségével:

#% 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és típusához 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 elküldéséhez: karakterlánc 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. típusok: Foo:! include types / Foo.raml Hiba:! include types / Error.raml / foos: get: description: Sorolja fel az összes Foos megfelelő lekérdezési feltételt, 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 [] példa:! tartalmaz példákat / Foos.json bejegyzés: leírás: Új Foo törzs létrehozása: alkalmazás / json: type: Foo példa:! include példák / Foo.json válaszok: 201: body: application / json: type: Foo példa:! include példák / Foo.json / {id}: get: leírás: Foo by id válaszok: 200: body: application / json: type: Foo példa:! include példák / Foo.json 404: body: application / json: type: Hibapélda:! include példák / Error.json put: leírás: Foo frissítése id törzs: alkalmazás / json: típus: Foo példa:! példák beillesztése / Foo.json válaszok: 200: törzs: alkalmazás / json: típus: Foo példa:! tartalmaz példák / Foo.json 404: törzs: alkalmazás / json: típus : Hibapélda:! Include példák / Error.json törlés: leírás: Foo törlése azonosító válaszokkal: 204: 404: body: application / json: type: Hibapélda:! Include example / Error.json / name / {name} : get: leírás: Sorolja fel az összes Foos-t bizonyos névvel: 200: body: application / json: type: Foo [] példa:! Include példák / Foos.json 

6. RAML eszközök

A RAML egyik nagyszerű dolga az eszköz támogatása.

Vannak eszközök a RAML API-k elemzéséhez, érvényesítéséhez és létrehozásához; eszközök az ügyfélkód létrehozásához; eszközök API dokumentáció előállításához HTML és PDF formátumban; és eszközök, amelyek segítenek minket a RAML API specifikáció szerinti tesztelésben.

Van még egy eszköz is, amely egy Swagger JSON API-t RAML-be konvertál.

Itt található egy minta az elérhető eszközökről:

  • API Designer - webalapú eszköz, amely a gyors és hatékony API tervezésre irányul
  • API Workbench - IDE a RESTful API-k tervezéséhez, felépítéséhez, teszteléséhez és dokumentálásához, amely támogatja a RAML 0.8 és 1.0 verziókat egyaránt
  • RAML Cop - a RAML fájlok érvényesítésének eszköze
  • RAML a JAX-RS-hez - eszközkészlet a Java + JAX-RS alkalmazáskód csontvázának előállításához RAML specifikációból, vagy RAML specifikáció előállításához egy meglévő JAX-RS alkalmazásból
  • RAML Sublime Plugin - szintaxis kiemelő plugin a Sublime szövegszerkesztőhöz
  • RAML-HTML - egy eszköz HTML-dokumentációk előállításához a RAML-ből
  • raml2pdf - egy eszköz a PDF dokumentáció előállításához a RAML-ből
  • RAML2Wiki - eszköz a Wiki dokumentációjának előállításához (Confluence / JIRA jelöléssel)
  • SoapUI RAML Plugin - RAML plugin a népszerű SoapUI funkcionális API tesztkészlethez
  • Vigia - integrációs tesztkészlet, amely RAML-definíció alapján tesztesetek generálására képes

A RAML-eszközök és a kapcsolódó projektek teljes listájához látogasson el a RAML-projektek oldalra.

7. A RAML jelenlegi állapota

A RAML 1.0 (RC) specifikáció kiadásjelölt státuszt kapott 2015. november 3-án, és az írás idején az 1.0 verzió várhatóan egy hónapon belül elkészült.

Elődje, a RAML 0.8 eredetileg 2014 őszén jelent meg, és még mindig számtalan eszköz támogatja.

8. További olvasmány

Íme néhány link, amelyeket hasznosnak találhatunk a RAML-lel végzett utazásunk során.

  • RAML.org - a RAML specifikáció hivatalos webhelye
  • json-schema.org - a JSON-séma otthona
  • A JSON séma megértése
  • JSON Schema Generator
  • Wikipédia RAML oldal

9. Következtetés

Ez a cikk bemutatta a RESTful API modellezési nyelvet (RAML). Bemutattunk néhány alapvető szintaxist egy egyszerű API specifikáció megírásához a RAML 1.0 (RC) specifikáció segítségével.

Megláttuk, hogyan tehetjük tömörebbé definícióinkat szintaktikai parancsikonok, valamint a példák, az adattípusok és a sémák „belefoglaló” fájlokká történő kiszervezésével.

Ezután bemutattuk a RAML specifikációival együttműködő hatékony eszközök gyűjteményét, amelyek segítenek a mindennapi API tervezésében, fejlesztésében, tesztelésében és dokumentálásában.

A specifikáció 1.0-ás verziójának közelgő hivatalos kiadásával, az eszközfejlesztők elsöprő támogatásával párosulva úgy tűnik, hogy a RAML itt marad.

Következő » Távolítsa el az elbocsátásokat a RAML-ben erőforrástípusokkal és tulajdonságokkal