Introduction à RAML - Le langage de modélisation d'API RESTful

Cet article fait partie d'une série: • Introduction à RAML - Le langage de modélisation d'API RESTful (article actuel) • Éliminer les redondances dans RAML avec les types de ressources et les traits

• RAML modulaire utilisant des inclusions, des bibliothèques, des superpositions et des extensions

• Définir des propriétés RAML personnalisées à l’aide d’annotations

1. Vue d'ensemble

Dans cet article, nous présentons le RESTful API Modeling Language (RAML), un langage à spécification ouverte indépendant du fournisseur, basé sur YAML 1.2 et JSON pour décrire les API RESTful.

Nous aborderons la syntaxe de base de RAML 1.0 et la structure des fichiers en montrant comment définir une API simple basée sur JSON. Nous montrerons également comment simplifier la maintenance des fichiers RAML grâce à l'utilisation d' includes . Et si vous avez des API héritées qui utilisent le schéma JSON, nous montrerons comment incorporer des schémas dans RAML.

Ensuite, nous présenterons une poignée d'outils qui peuvent améliorer votre parcours dans la RAML, notamment des outils de création, des générateurs de documentation et autres.

Enfin, nous terminerons en décrivant l'état actuel de la spécification RAML.

2. Définition de votre API (création du fichier .raml )

L'API que nous définirons est assez simple: étant donné les types d'entités Foo , définissez les opérations CRUD de base et quelques opérations de requête. Voici les ressources que nous définirons pour notre API:

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

Et définissons notre API comme étant sans état, en utilisant l'authentification HTTP Basic, et comme livrée cryptée via HTTPS. Enfin, choisissons JSON pour notre format de transport de données (XML est également pris en charge).

2.1. Paramètres de niveau racine

Nous allons commencer par créer un simple fichier texte nommé api.raml (le préfixe .raml est recommandé; le nom est arbitraire) et ajouter l'en-tête de la version RAML sur la première ligne. Au niveau racine du fichier, nous définissons les paramètres qui s'appliquent à l'ensemble de l'API:

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

Remarquez à la ligne 3 l'utilisation d'accolades {} autour du mot « version ». C'est ainsi que nous disons à RAML que « version» fait référence à une propriété et doit être développée. Par conséquent, la baseUri réelle sera: //myapi.mysite.com/v1

[Remarque: la propriété version est facultative et n'a pas besoin de faire partie de baseUri .]

2.2. Sécurité

La sécurité est également définie au niveau racine du fichier .raml . Ajoutons donc notre définition de schéma de sécurité de base HTTP:

securitySchemes: basicAuth: description: Each request must contain the headers necessary for basic authentication type: Basic Authentication describedBy: headers: Authorization: description: Used to send the Base64-encoded "username:password" credentials type: string responses: 401: description: | Unauthorized. Either the provided username and password combination is invalid, or the user is not allowed to access the content provided by the requested URL.

2.3. Types de données

Ensuite, nous définirons les types de données que notre API utilisera:

types: Foo: type: object properties: id: required: true type: integer name: required: true type: string ownerName: required: false type: string

L'exemple ci-dessus utilise une syntaxe développée pour définir nos types de données. RAML fournit des raccourcis syntaxiques pour rendre nos définitions de type moins verbeuses. Voici la section des types de données équivalents utilisant ces raccourcis:

types: Foo: properties: id: integer name: string ownerName?: string Error: properties: code: integer message: string

Le '?' Le caractère suivant un nom de propriété déclare que la propriété n'est pas requise.

2.4. Ressources

Nous allons maintenant définir la ressource de premier niveau (URI) de notre API:

/foos:

2.5. Paramètres URI

Ensuite, nous allons développer la liste des ressources, à partir de notre ressource de premier niveau:

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

Ici, les accolades {} autour des noms de propriété définissent les paramètres URI. Ils représentent des espaces réservés dans chaque URI et ne font pas référence aux propriétés de fichier RAML de niveau racine comme nous l'avons vu ci-dessus dans la déclaration baseUri . Les lignes ajoutées représentent les ressources / foos / {id} et / foos / name / {name} .

2.6. Méthodes

L'étape suivante consiste à définir les méthodes HTTP qui s'appliquent à chaque ressource:

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

2.7. Paramètres de requête

Nous allons maintenant définir un moyen d'interroger la collection foos à l' aide de paramètres de requête. Notez que les paramètres de requête sont définis à l'aide de la même syntaxe que celle utilisée ci-dessus pour les types de données:

/foos: get: description: List all Foos matching query criteria, if provided; otherwise list all Foos queryParameters: name?: string ownerName?: string

2.8. Réponses

Now that we've defined all of the resources for our API, including URI parameters, HTTP methods, and query parameters, it is time to define the expected responses and status codes. Response formats are typically defined regarding data types and examples.

JSON schema can be used instead of data types for backward compatibility with an earlier version of RAML. We'll introduce JSON schema in section 3.

[Note: In the code snippets below, a line containing only three dots (…) indicates that some lines are being skipped for brevity.]

Let's start with the simple GET operation on /foos/{id}:

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

This example shows that by performing a GET request on the resource /foos/{id}, we should get back the matching Foo in the form of a JSON object and an HTTP status code of 200.

Here is how we'd define the GET request on the /foos resource:

/foos: get: description: List all Foos matching query criteria, if provided; otherwise list all Foos queryParameters: name?: string ownerName?: string responses: 200: body: application/json: type: Foo[] example: | [ { "id" : 1, "name" : "First Foo" }, { "id" : 2, "name" : "Second Foo" } ] 

Note the use of square brackets [] appended to the Foo type. This demonstrates how we would define a response body containing an array of Foo objects, with the example being an array of JSON objects.

2.9. Request Body

Next, we'll define the request bodies that correspond to each POST and PUT request. Let's begin with creating a new Foo object:

/foos: ... post: description: Create a new Foo body: application/json: type: Foo example: { "id" : 5, "name" : "Another foo" } responses: 201: body: application/json: type: Foo example: { "id" : 5, "name" : "Another foo" } 

2.10. Status Codes

Note in the above example that when creating a new object, we return an HTTP status of 201. The PUT operation for updating an object will return an HTTP status of 200, utilizing the same request and response bodies as the POST operation.

In addition to the expected responses and status codes that we return when a request is successful, we can define the kind of response and a status code to expect when an error occurs.

Let's see how we would define the expected response for the GET request on the /foos/{id} resource when no resource is found with the given id:

 404: body: application/json: type: Error example: { "message" : "Not found", "code" : 1001 } 

3. RAML With JSON Schema

Before data types were introduced in RAML 1.0, objects, request bodies, and response bodies were defined using JSON Schema.

Using data types can be very powerful, but there are cases where you still want to use JSON Schema. In RAML 0.8 you defined your schemas using the root level schemas section.

That is still valid, but it is recommended to use the types section instead since the use of schemas may be deprecated in a future version. Both types and schemas, as well as type and schema, are synonymous.

Here is how you would define the Foo object type at the root level of the .raml file using JSON schema:

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

And here is how you would reference the schema in the GET /foos/{id} resource definition:

/foos: ... /{id}: get: description: Get a Foo by its id responses: 200: body: application/json: type: foo ...

4. Refactoring With Includes

As we can see from the above sections, our API is getting rather verbose and repetitive.

The RAML specification provides an include mechanism that allows us to externalize repeated and lengthy sections of code.

We can refactor our API definition using includes, making it more concise and less likely to contain the types of errors that result from the “copy/paste/fix everywhere” methodology.

For example, we can put the data type for a Foo object in the file types/Foo.raml and the type for an Error object in types/Error.raml. Then our types section would look like this:

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

And if we use JSON schema instead, our types section might look like this:

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

5. Completing the API

After externalizing all of the data types and examples to their files, we can refactor our API using the include facility:

#%RAML 1.0 title: Baeldung Foo REST Services API version: v1 protocols: [ HTTPS ] baseUri: //rest-api.baeldung.com/api/{version} mediaType: application/json securedBy: basicAuth securitySchemes: basicAuth: description: Each request must contain the headers necessary for basic authentication type: Basic Authentication describedBy: headers: Authorization: description: Used to send the Base64 encoded "username:password" credentials type: string responses: 401: description: | Unauthorized. Either the provided username and password combination is invalid, or the user is not allowed to access the content provided by the requested URL. types: Foo: !include types/Foo.raml Error: !include types/Error.raml /foos: get: description: List all Foos matching query criteria, if provided; otherwise list all Foos queryParameters: name?: string ownerName?: string responses: 200: body: application/json: type: Foo[] example: !include examples/Foos.json post: description: Create a new Foo body: application/json: type: Foo example: !include examples/Foo.json responses: 201: body: application/json: type: Foo example: !include examples/Foo.json /{id}: get: description: Get a Foo by id responses: 200: body: application/json: type: Foo example: !include examples/Foo.json 404: body: application/json: type: Error example: !include examples/Error.json put: description: Update a Foo by id body: application/json: type: Foo example: !include examples/Foo.json responses: 200: body: application/json: type: Foo example: !include examples/Foo.json 404: body: application/json: type: Error example: !include examples/Error.json delete: description: Delete a Foo by id responses: 204: 404: body: application/json: type: Error example: !include examples/Error.json /name/{name}: get: description: List all Foos with a certain name responses: 200: body: application/json: type: Foo[] example: !include examples/Foos.json 

6. RAML Tools

One of the great things about RAML is the tool support.

There are tools for parsing, validating, and authoring RAML APIs; tools for client code generation; tools for generating API documentation in HTML and PDF formats; and tools that assist us with testing against a RAML API specification.

There is even a tool that will convert a Swagger JSON API into RAML.

Here is a sampling of available tools:

  • API Designer – a web-based tool geared towards rapid and efficient API design
  • API Workbench – an IDE for designing, building, testing, and documenting RESTful APIs that supports both RAML 0.8 and 1.0
  • RAML Cop – a tool for validating RAML files
  • RAML for JAX-RS – a set of tools for generating a skeleton of Java + JAX-RS application code from a RAML spec, or for generating a RAML spec from an existing JAX-RS application
  • RAML Sublime Plugin – a syntax highlighter plugin for the Sublime text editor
  • RAML to HTML – a tool for generating HTML documentation from RAML
  • raml2pdf – a tool for generating PDF documentation from RAML
  • RAML2Wiki – a tool for generating Wiki documentation (using Confluence/JIRA markup)
  • SoapUI RAML Plugin – a RAML plugin for the popular SoapUI functional API testing suite
  • Vigia – an integration test suite capable of generating test cases based on a RAML definition

For a complete listing of RAML tools and related projects, visit the RAML Projects page.

7. The Current State of RAML

The RAML 1.0 (RC) specification gained release-candidate status on November 3, 2015, and at the time of this writing, version 1.0 was expected to be finalized within the month.

Its predecessor, RAML 0.8 was originally released in the Fall of 2014 and is still supported by a myriad of tools.

8. Further Reading

Here are some links that we may find useful along our journey with RAML.

  • RAML.org – the official site of the RAML specification
  • json-schema.org – the home of JSON schema
  • Understanding JSON Schema
  • JSON Schema Generator
  • Wikipedia RAML Page

9. Conclusion

This article introduced the RESTful API Modeling Language (RAML). We demonstrated some basic syntax for writing a simple API specification using the RAML 1.0 (RC) spec.

And we saw ways to make our definitions more concise by using syntactical shortcuts and externalizing examples, data types, and schemas into ‘include' files.

Then we introduced a collection of powerful tools that work with the RAML spec to assist with everyday API design, development, testing, and documentation tasks.

Avec la sortie officielle prochaine de la version 1.0 de la spécification, associée au soutien écrasant des développeurs d'outils, il semble que RAML est là pour rester.

Suivant » Éliminez les redondances dans la RAML avec les types de ressources et les traits