Uvod u RAML - RESTful API Modeling Language

Ovaj je članak dio niza: • Uvod u RAML - jezik za modeliranje RESTful API-a (trenutni članak) • Eliminiranje suvišnosti u RAML-u vrstama resursa i osobinama

• Modularno korištenje RAML-a uključuje, knjižnice, slojeve i proširenja

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

1. Pregled

U ovom članku uvodimo RESTful API Modeling Language (RAML), jezik neovisan od dobavljača, otvorene specifikacije, izgrađen na YAML 1.2 i JSON za opisivanje RESTful API-ja.

Obuhvatit ćemo osnovnu sintaksu RAML 1.0 i strukturu datoteka dok demonstriramo kako definirati jednostavni API zasnovan na JSON-u. Pokazat ćemo i kako pojednostaviti održavanje RAML datoteka pomoću uključuje. A ako imate naslijeđene API-je koji koriste JSON shemu, pokazat ćemo kako integrirati sheme u RAML.

Tada ćemo predstaviti nekoliko alata koji mogu poboljšati vaše putovanje u RAML, uključujući alate za autorizaciju, generatore dokumentacije i druge.

Na kraju ćemo završiti opisom trenutnog stanja specifikacije RAML-a.

2. Definiranje vašeg API-ja (Izrada .raml datoteka)

API koji ćemo definirati prilično je jednostavan: s obzirom na vrste entiteta Foo, definirajte osnovne CRUD operacije i nekoliko operacija upita. Evo resursa koje ćemo definirati za naš API:

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

A definirajmo naš API da nema državljanstvo, koristeći HTTP Basic provjeru autentičnosti i da se isporučuje šifrirano putem HTTPS-a. Konačno, odaberemo JSON za naš format prijenosa podataka (XML je također podržan).

2.1. Postavke na razini korijena

Počet ćemo izradom jednostavne tekstualne datoteke s imenom api.raml ( .raml preporučuje se prefiks; naziv je proizvoljan) i dodajte zaglavlje verzije RAML-a u redak jedan. Na korijenskoj razini datoteke definiramo postavke koje se primjenjuju na cijeli API:

#% RAML 1.0 naslov: Baeldung Foo REST Services API koristeći verzije Data Types: v1 protokoli: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json

Obavijest u retku 3 o upotrebi zagrada {} oko riječi „verzija“. Ovako kažemo RAML-u da „verzija" odnosi se na nekretninu i treba ga proširiti. Stoga stvarni baseUri bit će: //myapi.mysite.com/v1

[Napomena: verzija svojstvo je neobavezno i ​​ne mora biti dio baseUri.]

2.2. Sigurnost

Sigurnost je također definirana na korijenskoj razini .raml datoteka. Pa dodajmo našu definiciju HTTP osnovne sigurnosne sheme:

securitySchemes: basicAuth: description: Svaki zahtjev mora sadržavati zaglavlja potrebna za osnovni tip provjere autentičnosti: Basic Authentication descriBy: headers: Authorization: description: Koristi se za slanje Base64 kodiranih vjerodajnica "username: password" vrsta: string odgovori: 401: description: | 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.

2.3. Vrste podataka

Zatim ćemo definirati vrste podataka koje će koristiti naš API:

tipovi: Foo: tip: svojstva objekta: id: obavezno: istinski tip: cijelo ime: obavezno: istiniti tip: string ownerName: obavezno: lažni tip: string

Gornji primjer koristi proširenu sintaksu za definiranje naših vrsta podataka. RAML nudi neke sintaksičke prečace kako bi naše definicije tipova bile manje opširne. Evo odjeljka o ekvivalentnim vrstama podataka pomoću ovih prečaca:

vrste: Foo: svojstva: id: cijelo ime: niz ime vlasnika ?: niz Pogreška: svojstva: kod: cijela poruka: niz

Znak "?" znak nakon imena svojstva izjavljuje da svojstvo nije potrebno.

2.4. Resursi

Sada ćemo definirati resurs najviše razine (URI) našeg API-ja:

/ foos:

2.5. URI parametri

Zatim ćemo proširiti popis resursa, gradeći se iz našeg najvišeg nivoa resursa:

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

Ovdje zagrade {} oko imena svojstava definiraju URI parametre. Oni predstavljaju rezervirana mjesta u svakom URI-ju i ne odnose se na svojstva RAML datoteke na korijenskoj razini kao što smo vidjeli gore u baseUri deklaracija. Dodani redovi predstavljaju resurse / foos / {id} i / foos / name / {name}.

2.6. Metode

Sljedeći je korak definiranje HTTP metoda koje se primjenjuju na svaki resurs:

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

2.7. Parametri upita

Sada ćemo definirati način za postavljanje upita foos prikupljanje pomoću parametara upita. Imajte na umu da su parametri upita definirani pomoću iste sintakse koju smo gore koristili za tipove podataka:

/ foos: get: description: Navedite sve Foos koji odgovaraju kriterijima upita, ako su navedeni; u suprotnom navesti sve Foos queryParameters: name ?: string ownerName ?: string

2.8. Odgovori

Sad kad smo definirali sve resurse za naš API, uključujući URI parametre, HTTP metode i parametre upita, vrijeme je da definiramo očekivane odgovore i statusne kodove. Formati odgovora obično se definiraju s obzirom na vrste podataka i primjere.

JSON shema može se koristiti umjesto tipova podataka za povratnu kompatibilnost s starijom verzijom RAML-a. JSON shemu predstavit ćemo u odjeljku 3.

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

Krenimo s jednostavnom operacijom GET / foos / {id}:

/ foos: ... / {id}: get: description: Nabavite Foo po id odgovorima: 200: body: application / json: type: Foo primjer: {"id": 1, "name": "First Foo" }

Ovaj primjer pokazuje da izvođenjem GET zahtjeva na resursu / foos / {id}, trebali bismo vratiti podudaranje Foo u obliku JSON objekta i HTTP statusnog koda 200.

Evo kako bismo definirali GET zahtjev na / foos resurs:

/ 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 [] primjer: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}]

Obratite pažnju na upotrebu uglatih zagrada [] dodanih na Foo tip. Ovo pokazuje kako bismo definirali tijelo odgovora koje sadrži niz Foo objekata, s tim da je primjer niz JSON objekata.

2.9. Tijelo zahtjeva

Zatim ćemo definirati tijela zahtjeva koja odgovaraju svakom POST i PUT zahtjevu. Počnimo sa stvaranjem novog Foo objekt:

/ foos: ... post: description: Stvorite novo tijelo Foo: application / json: type: Foo primjer: {"id": 5, "name": "Another foo"} odgovori: 201: body: application / json : type: Foo primjer: {"id": 5, "name": "Drugi foo"}

2.10. Kodovi statusa

Primijetite u gornjem primjeru da prilikom stvaranja novog objekta vraćamo HTTP status od 201. Operacija PUT za ažuriranje objekta vratit će HTTP status od 200, koristeći ista tijela zahtjeva i odgovora kao i operacija POST.

Pored očekivanih odgovora i statusnih kodova koje vraćamo kada je zahtjev uspješan, možemo definirati vrstu odgovora i statusni kod koji se očekuju kada se dogodi pogreška.

Pogledajmo kako bismo definirali očekivani odgovor na GET zahtjev na / foos / {id} resurs kada nije pronađen resurs s danim id-om:

 404: body: application / json: type: Primjer pogreške: {"message": "Not found", "code": 1001}

3. RAML s JSON shemom

Prije vrste podataka uvedeni su u RAML 1.0, objekti, tijela zahtjeva i tijela odgovora definirani su pomoću JSON sheme.

Koristeći vrste podataka može biti vrlo moćan, ali postoje slučajevi u kojima i dalje želite koristiti JSON shemu. U RAML-u 0.8 definirali ste svoje sheme pomoću korijenske razine sheme odjeljak.

To još uvijek vrijedi, ali preporučljivo je koristiti vrste odjeljak umjesto upotrebe sheme može biti zastarjelo u budućoj verziji. Oba vrste i sheme, kao i tip i shema, su sinonimi.

Evo kako biste definirali vrstu objekta Foo na korijenskoj razini .raml datoteka koja koristi JSON shemu:

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

I evo kako biste uputili shemu u GET / foos / {id} definicija resursa:

/ foos: ... / {id}: get: description: Dobijte Foo po njegovim ID odgovorima: 200: body: application / json: type: foo ...

4. Refaktoriranje s uključuje

Kao što vidimo iz gornjih odjeljaka, naš API postaje prilično detaljan i ponavlja se.

Specifikacija RAML-a pruža mehanizam uključivanja koji nam omogućuje eksternaliziranje ponovljenih i podužih dijelova koda.

Možemo refaktorizirati našu definiciju API-ja koristeći include, čineći je jezgrovitijom i manje vjerojatno da će sadržavati vrste pogrešaka koje proizlaze iz metodologije "kopiraj / zalijepi / popravi svugdje".

Na primjer, možemo staviti tip podataka za Foo objekt u datoteci vrste / Foo.raml i tip za Pogreška objekt u vrste / Pogreška.raml. Zatim naš vrste odjeljak bi izgledao ovako:

tipovi: Foo:! uključuju vrste / Pogreška Foo.raml:! uključuju tipove / Error.raml

A ako umjesto toga koristimo JSON shemu, naš vrste odjeljak može izgledati ovako:

vrste: foo:! uključuju schemas / foo.json pogreška:! uključuju schemas / error.json

5. Dovršavanje API-ja

Nakon eksternalizacije svih vrsta podataka i primjera u njihove datoteke, možemo refaktorizirati naš API pomoću značajke include:

#% 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 osnovnu vrstu provjere autentičnosti: Osnovna opisana provjera autentičnostiBy: zaglavlja: Ovlaštenje: opis: Koristi se za slanje vjerodajnica Base64 kodiranih "korisničko ime: lozinka" vrsta: niz odgovora: 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 vrste / Pogreška Foo.raml:! uključuju tipove / Error.raml / foos: get: description: Popis svih Foo-a koji odgovaraju kriterijima upita, ako su navedeni; u suprotnom navesti sve Foos queryParameters: name ?: string ownerName ?: string odgovori: 200: body: application / json: type: Foo [] primjer:! uključuju primjere / Foos.json post: description: Stvoriti novo Foo tijelo: application / json: type: Foo primjer:! uključuju primjere / Foo.json odgovori: 201: body: application / json: type: Foo primjer:! uključuju primjere / Foo.json / {id}: get: description: Dobivanje Foo-a po id-u odgovori: 200: body: application / json: type: Foo primjer:! uključuju primjere / Foo.json 404: body: application / json: type: Primjer pogreške:! uključuju primjere / Error.json put: description: Ažuriranje Foo-a pomoću id tijelo: application / json: type: Foo primjer:! uključuju primjere / Foo.json odgovori: 200: body: application / json: type: Foo primjer:! uključuju primjere / Foo.json 404: body: application / json: type : Primjer pogreške:! Uključuju primjere / Error.json delete: description: Izbrišite Foo po id odgovorima: 204: 404: body: application / json: type: Primjer pogreške:! Include examples / Error.json / name / {name} : get: description: Popis svih Foo-a s određenim odgovorima na ime: 200: body: application / json: type: Foo [] primjer:! Uključuju primjere / Foos.json

6. RAML alati

Jedna od sjajnih stvari u vezi s RAML-om je podrška za alate.

Postoje alati za raščlanjivanje, provjeru valjanosti i autoriranje RAML API-ja; alati za generiranje klijentskog koda; alati za generiranje API dokumentacije u HTML i PDF formatima; i alati koji nam pomažu u testiranju prema RAML API specifikaciji.

Postoji čak i alat koji će pretvoriti Swagger JSON API u RAML.

Evo uzorka dostupnih alata:

  • API Designer - internetski alat usmjeren prema brzom i učinkovitom API dizajnu
  • API Workbench - IDE za dizajniranje, izgradnju, testiranje i dokumentiranje RESTful API-ja koji podržava RAML 0.8 i 1.0
  • RAML Cop - alat za provjeru valjanosti RAML datoteka
  • RAML za JAX-RS - skup alata za generiranje kostura Java + JAX-RS aplikacijskog koda iz RAML specifikacije ili za generiranje RAML specifikacija iz postojeće JAX-RS aplikacije
  • RAML Sublime Plugin - dodatak za isticanje sintakse za Sublime editor teksta
  • RAML u HTML - alat za generiranje HTML dokumentacije iz RAML-a
  • raml2pdf - alat za generiranje PDF dokumentacije iz RAML-a
  • RAML2Wiki - alat za generiranje Wiki dokumentacije (pomoću oznake Confluence / JIRA)
  • Dodatak SoapUI RAML - dodatak RAML za popularni paket za testiranje funkcionalnih API-ja SoapUI
  • Vigia - integracijski testni paket sposoban generirati test slučajeve na temelju RAML definicije

Za cjelovit popis RAML alata i srodnih projekata posjetite stranicu RAML projekti.

7. Trenutno stanje RAML-a

Specifikacija RAML 1.0 (RC) stekla je status kandidata za objavljivanje 3. studenoga 2015., a u vrijeme pisanja ovog članka, verzija 1.0 trebala je biti finalizirana tijekom mjeseca.

Njegov prethodnik, RAML 0.8, izvorno je objavljen u jesen 2014. godine, a još uvijek ga podržava bezbroj alata.

8. Daljnje čitanje

Evo nekoliko poveznica koje bi nam mogle biti korisne tijekom našeg putovanja s RAML-om.

  • RAML.org - službena stranica specifikacije RAML-a
  • json-schema.org - dom JSON sheme
  • Razumijevanje JSON sheme
  • JSON Generator sheme
  • Wikipedia RAML Stranica

9. Zaključak

Ovaj je članak predstavio RESTful API Modeling Language (RAML). Pokazali smo osnovnu sintaksu za pisanje jednostavne API specifikacije koristeći specifikaciju RAML 1.0 (RC).

Vidjeli smo načine kako naše definicije učiniti sažetijim upotrebom sintaksičkih prečaca i eksternaliziranjem primjera, vrsta podataka i shema u datoteke 'uključi'.

Zatim smo predstavili kolekciju moćnih alata koji rade s RAML specifikacijama kako bi pomogli u svakodnevnim zadacima API dizajna, razvoja, testiranja i dokumentacije.

S predstojećim službenim izdanjem verzije 1.0 specifikacije, zajedno s ogromnom podrškom programera alata, čini se da je RAML tu da ostane.

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

Popularni Postovi

Najnoviji postovi

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