Inleiding tot RAML - De RESTful API-modelleringstaal

Dit artikel maakt deel uit van een reeks: • Inleiding tot RAML - De RESTful API-modelleringstaal (huidig ​​artikel) • Elimineer redundanties in RAML met resourcetypen en -eigenschappen

• Modulaire RAML met behulp van inclusief, bibliotheken, overlays en uitbreidingen

• Definieer aangepaste RAML-eigenschappen met behulp van annotaties

1. Overzicht

In dit artikel introduceren we de RESTful API Modeling Language (RAML), een leverancier-neutrale, open specificatietaal gebouwd op YAML 1.2 en JSON voor het beschrijven van RESTful API's.

We behandelen de standaard RAML 1.0-syntaxis en bestandsstructuur terwijl we demonstreren hoe een eenvoudige JSON-gebaseerde API kan worden gedefinieerd. We laten ook zien hoe u het onderhoud van RAML-bestanden kunt vereenvoudigen door het gebruik van omvat. En als u verouderde API's heeft die JSON-schema gebruiken, laten we zien hoe u schema's in RAML kunt opnemen.

Vervolgens introduceren we een handvol tools die uw reis naar RAML kunnen verbeteren, waaronder authoringtools, documentatiegeneratoren en andere.

Ten slotte sluiten we af met een beschrijving van de huidige status van de RAML-specificatie.

2. Uw API definiëren (het .raml het dossier)

De API die we zullen definiëren is vrij eenvoudig: gezien de entiteitstypen Foo, definieer basis CRUD-bewerkingen en een aantal query-bewerkingen. Dit zijn de bronnen die we voor onze API zullen definiëren:

  • GET / api / v1 / foos
  • POST / api / v1 / foos
  • GET / api / v1 / foos / {id}
  • PUT / api / v1 / foos / {id}
  • VERWIJDEREN / api / v1 / foos / {id}
  • GET / api / v1 / foos / naam / {naam}
  • GET / api / v1 / foos? Name = {name} & ownerName = {ownerName}

En laten we onze API definiëren als staatloos, met behulp van HTTP Basic-authenticatie, en versleuteld via HTTPS worden afgeleverd. Laten we tot slot JSON kiezen voor ons datatransportformaat (XML wordt ook ondersteund).

2.1. Instellingen op rootniveau

We beginnen met het maken van een eenvoudig tekstbestand met de naam api.raml (de .raml prefix wordt aanbevolen; de naam is willekeurig) en voeg de RAML-versieheader toe op regel één. Op het rootniveau van het bestand definiëren we instellingen die van toepassing zijn op de hele API:

#% RAML 1.0 titel: Baeldung Foo REST Services API met gegevenstypen versie: v1-protocollen: [HTTPS] baseUri: //myapi.mysite.com/api/{version} mediaType: application / json 

Let op regel 3 op het gebruik van accolades {} rond het woord 'versie“. Dit is hoe we RAML vertellen dat "versie" verwijst naar een eigenschap en moet worden uitgebreid. Daarom de feitelijke baseUri zal zijn: //myapi.mysite.com/v1

[Merk op versie eigenschap is optioneel en hoeft geen deel uit te maken van de baseUri.]

2.2. Veiligheid

Beveiliging wordt ook gedefinieerd op het rootniveau van het .raml het dossier. Laten we dus onze definitie van het HTTP-basisbeveiligingsschema toevoegen:

securitySchemes: basicAuth: description: Elk verzoek moet de headers bevatten die nodig zijn voor het basisverificatietype: Basisverificatie beschrevenBy: headers: Autorisatie: beschrijving: Wordt gebruikt om het Base64-gecodeerde "gebruikersnaam: wachtwoord" -referentietype te verzenden: stringantwoorden: 401: beschrijving: | Ongeautoriseerd. De opgegeven combinatie van gebruikersnaam en wachtwoord is ongeldig, of de gebruiker heeft geen toegang tot de inhoud van de gevraagde URL.

2.3. Gegevenstypen

Vervolgens zullen we de gegevenstypen definiëren die onze API zal gebruiken:

types: Foo: type: object eigenschappen: id: vereist: waar type: geheel getal naam: vereist: waar type: tekenreeks eigenaarnaam: vereist: onwaar type: tekenreeks

Het bovenstaande voorbeeld gebruikt uitgebreide syntaxis voor het definiëren van onze gegevenstypen. RAML biedt enkele syntactische snelkoppelingen om onze typedefinities minder uitgebreid te maken. Hier is het gedeelte met equivalente gegevenstypen met behulp van deze snelkoppelingen:

types: Foo: eigenschappen: id: integer naam: string ownerName ?: string Fout: eigenschappen: code: integer bericht: string

De '?' teken achter een eigenschapnaam geeft aan dat de eigenschap niet vereist is.

2.4. Middelen

Nu gaan we de resource op het hoogste niveau (URI) van onze API definiëren:

/ foos:

2.5. URI-parameters

Vervolgens breiden we de lijst met bronnen uit op basis van onze bron op het hoogste niveau:

/ foos: / {id}: / naam / {naam}: 

Hier definiëren de accolades {} rond eigenschapsnamen URI-parameters. Ze vertegenwoordigen tijdelijke aanduidingen in elke URI en verwijzen niet naar RAML-bestandseigenschappen op rootniveau, zoals we hierboven hebben gezien in de baseUri verklaring. De toegevoegde regels vertegenwoordigen de bronnen / foos / {id} en / foos / name / {name}.

2.6. Methoden

De volgende stap is het definiëren van de HTTP-methoden die van toepassing zijn op elke bron:

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

2.7. Queryparameters

Nu zullen we een manier definiëren om het foos verzameling met behulp van queryparameters. Merk op dat queryparameters worden gedefinieerd met dezelfde syntaxis die we hierboven hebben gebruikt voor gegevenstypen:

/ foos: get: description: Maak een lijst van alle Foos die overeenkomen met zoekcriteria, indien opgegeven; geef anders alle Foos queryParameters: name ?: string ownerName ?: string

2.8. Reacties

Nu we alle bronnen voor onze API hebben gedefinieerd, inclusief URI-parameters, HTTP-methoden en queryparameters, is het tijd om de verwachte reacties en statuscodes te definiëren. Antwoordformaten worden doorgaans gedefinieerd met betrekking tot gegevenstypen en voorbeelden.

JSON-schema kan worden gebruikt in plaats van gegevenstypen voor achterwaartse compatibiliteit met een eerdere versie van RAML. We introduceren het JSON-schema in sectie 3.

[Opmerking: in de onderstaande codefragmenten geeft een regel met slechts drie punten (…) aan dat sommige regels worden overgeslagen om het kort te houden.]

Laten we beginnen met de eenvoudige GET-bewerking / foos / {id}:

/ foos: ... / {id}: get: description: Get a Foo by id response: 200: body: application / json: type: Foo voorbeeld: {"id": 1, "name": "First Foo" } 

Dit voorbeeld laat zien dat door een GET-verzoek op de bron uit te voeren / foos / {id}, we moeten de overeenkomst terugkrijgen Foo in de vorm van een JSON-object en een HTTP-statuscode van 200.

Hier is hoe we het GET-verzoek op het / foos bron:

/ foos: get: description: Maak een lijst van alle Foos die overeenkomen met zoekcriteria, indien opgegeven; lijst anders alle Foos queryParameters: name ?: string ownerName ?: stringantwoorden: 200: body: application / json: type: Foo [] voorbeeld: | [{"id": 1, "name": "First Foo"}, {"id": 2, "name": "Second Foo"}] 

Let op het gebruik van vierkante haken [] die aan de Foo type. Dit laat zien hoe we een responsbody zouden definiëren met een array van Foo objecten, met als voorbeeld een array van JSON-objecten.

2.9. Aanvraaginstantie

Vervolgens definiëren we de aanvraaginstanties die overeenkomen met elke POST- en PUT-aanvraag. Laten we beginnen met het maken van een nieuw Foo voorwerp:

/ foos: ... post: description: Maak een nieuwe Foo body: application / json: type: Foo voorbeeld: {"id": 5, "name": "Another foo"} reacties: 201: body: application / json : type: Foo voorbeeld: {"id": 5, "name": "Another foo"} 

2.10. Statuscodes

Merk op dat in het bovenstaande voorbeeld bij het aanmaken van een nieuw object, we de HTTP-status 201 retourneren. De PUT-bewerking voor het bijwerken van een object retourneert een HTTP-status van 200, waarbij dezelfde aanvraag- en antwoordtekst wordt gebruikt als de POST-bewerking.

Naast de verwachte reacties en statuscodes die we retourneren wanneer een verzoek succesvol is, kunnen we het soort reactie en een statuscode definiëren die we kunnen verwachten als er een fout optreedt.

Laten we eens kijken hoe we het verwachte antwoord voor het GET-verzoek op het / foos / {id} bron als er geen bron wordt gevonden met de opgegeven id:

 404: body: application / json: type: Foutvoorbeeld: {"message": "Niet gevonden", "code": 1001} 

3. RAML met JSON-schema

Voordat gegevenstypen werden geïntroduceerd in RAML 1.0, objecten, aanvraaginstanties en reactie-instanties werden gedefinieerd met behulp van JSON-schema.

Gebruik makend van gegevenstypen kan erg krachtig zijn, maar er zijn gevallen waarin u nog steeds JSON-schema wilt gebruiken. In RAML 0.8 heb je je schema's gedefinieerd met behulp van het root-niveau schema's sectie.

Dat is nog steeds geldig, maar het wordt aanbevolen om de types sectie in plaats sinds het gebruik van schema's mogelijk verouderd in een toekomstige versie. Beide types en schema's, net zoals type en schema, zijn synoniem.

Hier is hoe u het Foo-objecttype op het rootniveau van het .raml bestand met JSON-schema:

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

En hier is hoe u zou verwijzen naar het schema in de GET / foos / {id} resource definitie:

/ foos: ... / {id}: get: description: Verkrijg een Foo door zijn id reacties: 200: body: application / json: type: foo ...

4. Refactoring met omvat

Zoals we in de bovenstaande secties kunnen zien, wordt onze API nogal uitgebreid en repetitief.

De RAML-specificatie biedt een include-mechanisme waarmee we herhaalde en lange secties van code kunnen externaliseren.

We kunnen onze API-definitie herstructureren met behulp van include, waardoor deze beknopter wordt en minder waarschijnlijk de soorten fouten bevat die het gevolg zijn van de methodologie "overal kopiëren / plakken / repareren".

We kunnen bijvoorbeeld het gegevenstype plaatsen voor een Foo object in het bestand types / Foo.raml en het type voor een Fout bezwaar in types / Error.raml. Dan onze types sectie zou er als volgt uitzien:

types: Foo:! include types / Foo.raml Fout:! include types / Error.raml

En als we in plaats daarvan het JSON-schema gebruiken, is onze types sectie kan er als volgt uitzien:

types: foo:! include schemas / foo.json error:! include schemas / error.json

5. Voltooien van de API

Nadat we alle gegevenstypen en voorbeelden naar hun bestanden hebben geëxternaliseerd, kunnen we onze API refactoren met behulp van de include-faciliteit:

#% RAML 1.0 titel: Baeldung Foo REST Services API-versie: v1-protocollen: [HTTPS] baseUri: //rest-api.baeldung.com/api/{version} mediatype: applicatie / json beveiligd Door: basicAuth securitySchemes: basicAuth: beschrijving: Elk verzoek moet de headers bevatten die nodig zijn voor het basisauthenticatietype: Basisauthenticatie beschreven Door: headers: Autorisatie: beschrijving: Wordt gebruikt om de met Base64 gecodeerde "gebruikersnaam: wachtwoord" -referenties te verzenden type: stringreacties: 401: beschrijving: | Ongeautoriseerd. De opgegeven combinatie van gebruikersnaam en wachtwoord is ongeldig, of de gebruiker heeft geen toegang tot de inhoud van de gevraagde URL. types: Foo:! include types / Foo.raml Fout:! include types / Error.raml / foos: get: description: Maak een lijst van alle Foos die overeenkomen met zoekcriteria, indien opgegeven; anders lijst alle Foos queryParameters: name ?: string ownerName ?: stringantwoorden: 200: body: application / json: type: Foo [] voorbeeld:! include voorbeelden / Foos.json post: description: Maak een nieuwe Foo body: application / json: type: Foo voorbeeld:! include voorbeelden / Foo.json reacties: 201: body: application / json: type: Foo voorbeeld:! include voorbeelden / Foo.json / {id}: get: description: Krijg een Foo door id reacties: 200: body: application / json: type: Foo voorbeeld:! include voorbeelden / Foo.json 404: body: application / json: type: Fout voorbeeld:! include voorbeelden / Error.json put: description: Update een Foo door id body: application / json: type: Foo voorbeeld:! include voorbeelden / Foo.json reacties: 200: body: application / json: type: Foo voorbeeld:! include voorbeelden / Foo.json 404: body: application / json: type : Voorbeeld van een fout:! Include voorbeelden / Error.json delete: description: Verwijder een Foo op ID-antwoorden: 204: 404: body: application / json: type: Error example:! Include samples / Error.json / name / {name} : get: description: Maak een lijst van alle Foos met een bepaalde naam antwoorden: 200: body: application / json: type: Foo [] voorbeeld:! Include voorbeelden / Foos.json 

6. RAML-hulpmiddelen

Een van de geweldige dingen van RAML is de toolondersteuning.

Er zijn tools voor het parseren, valideren en schrijven van RAML-API's; tools voor het genereren van klantcodes; tools voor het genereren van API-documentatie in HTML- en PDF-formaten; en tools die ons helpen bij het testen op basis van een RAML API-specificatie.

Er is zelfs een tool die een Swagger JSON API omzet in RAML.

Hier is een greep uit de beschikbare tools:

  • API Designer - een webgebaseerde tool gericht op snel en efficiënt API-ontwerp
  • API Workbench - een IDE voor het ontwerpen, bouwen, testen en documenteren van RESTful API's die zowel RAML 0.8 als 1.0 ondersteunt
  • RAML Cop - een tool voor het valideren van RAML-bestanden
  • RAML voor JAX-RS - een set tools voor het genereren van een skelet van Java + JAX-RS-applicatiecode van een RAML-specificatie, of voor het genereren van een RAML-specificatie van een bestaande JAX-RS-applicatie
  • RAML Sublime Plugin - een syntaxis markeerstift plugin voor de Sublime teksteditor
  • RAML naar HTML - een tool voor het genereren van HTML-documentatie van RAML
  • raml2pdf - een tool voor het genereren van PDF-documentatie van RAML
  • RAML2Wiki - een tool voor het genereren van Wiki-documentatie (met behulp van Confluence / JIRA-markup)
  • SoapUI RAML-plug-in - een RAML-plug-in voor de populaire SoapUI functionele API-testsuite
  • Vigia - een integratietestsuite die testcases kan genereren op basis van een RAML-definitie

Bezoek de pagina RAML-projecten voor een volledige lijst met RAML-tools en gerelateerde projecten.

7. De huidige status van RAML

De RAML 1.0 (RC) -specificatie kreeg op 3 november 2015 de status van release-candidate, en op het moment van schrijven werd verwacht dat versie 1.0 binnen een maand zou worden afgerond.

Zijn voorganger, RAML 0.8, werd oorspronkelijk uitgebracht in de herfst van 2014 en wordt nog steeds ondersteund door een groot aantal tools.

8. Verder lezen

Hier zijn enkele links die we mogelijk nuttig vinden tijdens onze reis met RAML.

  • RAML.org - de officiële site van de RAML-specificatie
  • json-schema.org - de thuisbasis van het JSON-schema
  • Inzicht in JSON-schema
  • JSON-schemagenerator
  • Wikipedia RAML-pagina

9. Conclusie

In dit artikel is de RESTful API Modeling Language (RAML) geïntroduceerd. We hebben een aantal basissyntaxis gedemonstreerd voor het schrijven van een eenvoudige API-specificatie met behulp van de RAML 1.0 (RC) -specificatie.

En we hebben manieren gezien om onze definities beknopter te maken door syntactische snelkoppelingen en externaliserende voorbeelden, gegevenstypen en schema's in ‘include'-bestanden te gebruiken.

Vervolgens hebben we een verzameling krachtige tools geïntroduceerd die werken met de RAML-specificatie om u te helpen bij alledaagse API-ontwerp-, ontwikkelings-, test- en documentatietaken.

Met de aanstaande officiële release van versie 1.0 van de specificatie, in combinatie met de overweldigende ondersteuning van ontwikkelaars van tools, lijkt het erop dat RAML er is om te blijven.

De volgende » Elimineer overtolligheden in RAML met resourcetypen en eigenschappen