RAML dans les détails.
Dans l'article suivant, je vais parler plus en détail des fonctionnalités offertes par le RAML.
Comment définir une API, comment définir les paramètres, comment définir les réponses, etc ...
Description du document
#%RAML 0.8
title: API d'Exemple
version: v1
Ici la balise RAML sert à décrire sur quelle version de spécification RAML on se base.
Le titre est tout simplement le titre général de l'API, généralement le nom de votre site.
La version permet d'identifier clairement sur quelle version de description de notre API nous sommes.
Description d'un point d'entrée
Ensuite nous allons devoir définir un point d'entrée :
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
Ici /api-action est l'url qui permettra d'accéder à notre api REST, par exemple : www.monsite.fr/api-action .Ensuite à nous de définir des méthodes GET / POST / PUT / DELETE / etc ... pour intéragir avec notre API.
Un exemple avec un GET.
Un GET peut avoir des paramètres, mais pas de body (pourtant a priori rien ne l'interdit, mais la plupart des clients ne l'autorisent pas et API Designer non plus).
Voici la description d'un GET:
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/list:
get:
...
Ici get est le mot clé, il peut donc prendre les valeurs suivantes : connect, delete, post, patch, put, trace, ... en bref l'ensemble des actions REST possibles.
Ajout de paramètres
Nous allons maintenant lui définir des paramètres.
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/list:
get:
queryParameters:
params1:
displayName: Params 1
type: integer
description: filtre sur la date
example: 1398792157
required: false
Nous avons donc défini que notre requête pouvait prendre des paramètres grâce à queryParameters. Nous avons aussi défini un paramètre : params1.
Celui-ci est decrit, c'est un integer (grâce au type), il est non obligatoire (required: false). Et nous avons aussi d'autres informations pratiques description et displayName qui permet simplement d'avoir un nom affiché différent du paramètre en lui même.
Il est possible d'ajouter des paramètres, il suffit de répéter la chose :
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/list:
get:
queryParameters:
params1:
displayName: Params 1
type: integer
description: filtre sur la date
example: 1398792157
required: false
params2:
displayName: Params 2
type: string
description: filtre sur l'état
example: done
required: false
Et ceci autant de fois que nécessaire.
Voici actuellement le rendu de notre API :
Mais il est possible aussi de définir un get directement avec un paramètre dans l'url, exemple :
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/{id}/show:
get:
queryParameters:
params1:
displayName: Params 1
type: integer
description: filtre sur la date
example: 1398792157
required: false
Voici le résultat :
Voici l'ensemble des types acceptables par RAML :
- string
- number
- integer
- date
- boolean
- file (uniquement en POST)
Mais nous avons aussi plus d'options possibles :
- enum : seulement pour le type string
- pattern : seulement pour le type string (type Perl 5)
- minLength : seulement pour le type string
- maxLength : seulement pour le type string
- minimum : seulement pour le type number ou integer
- maximum : seulement pour le type number ou integer
- repeat : permet de passer plusieurs fois le même paramètre
- default
L'ensemble de ces informations est optionnel tout comme displayName, type, description, example, required.
Dans les cas autres qu'un get, il est possible de passer en plus un body.
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/select:
post:
body:
application/json:
schema: |
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
example: |
["12315412131" ,"12315412145"]
Ici le body permet de nous définir que l'on attend forcément un body, celui-ci peut être ici uniquement de type application/json, cependant, il est tout à fait possible de le mettre en :
- application/x-www-form-urlencoded
- application/xml
- multipart/form-data
Mais aussi d'en avoir plusieurs (accepter des body JSON et XML par exemple)
Nous avons aussi décrit un schéma de validation pour notre JSON (il est bien sûr aussi possible d'en faire un pour xml). Celui-ci permettra d'assurer vos échanges dans un bon format et de faire en sorte le bouchon (mock) vous retourne directement l'information si les paramètres sont mal formés.
Reponse
Nous allons maintenant nous intéresser à la réponse.
#%RAML 0.8
title: API d'Exemple
version: v1
/api-action:
/list:
get:
description: |
Exemple 1, Quid enim tam absurdum quam delectari multis inanimis rebus, ut honore, ut gloria, ut aedificio, ut vestitu cultuque corporis, animante virtute praedito
queryParameters:
params1:
displayName: Params 1
type: integer
description: filtre sur la date
example: 1398792157
required: false
responses:
200:
description: |
Retourne un tableau JSON
body:
application/json:
schema: |
{
"type": "array",
"items": {
"type": "object",
"description" : "Information",
"properties": {
"reference": {
"description" : "la reference",
"type": "string",
"required":true
}
} } }
example: |
[
{ reference: '1234567890123' },
{ reference: '1234567890125' }
]
Voici une réponse complète.
- 200 : représente le code HTTP.
- description : permet de donner rapidement une description de la réponse
- application/json : spécifie le type de réponse attendue (mais nous pouvons aussi avoir du xml)
- schema : précise le schéma de validation de la réponse
- exemple : donne simplement un exemple de réponse (celui rendu par le mock)
Et en voici le rendu :
Il est bien sûr possible d'ajouter des codes de réponse. Voici les plus utilisés :
- 200 : OK
- 201 : Création effectuée
- 204 : Requête traitée mais pas de retour attendu
- 400 : Mauvaise requête
- 401 : Non autorisé à effectuer cette requête
- 403 : Interdiction d'effectuer cette requête
- 404 : Not Found
- 405 : Méthode non autorisée
- 409 : Conflit
- 500 : Erreur serveur
Sinon, vous pouvez regarder la liste ici : Liste de code réponse
Attention, il est possible d'ajouter autant de codes réponses que souhaitez, cependant il est impossible d'ajouter deux exemples de réponses d'un code spécifique (ex: 500). C'est un peu dommage.
Try it ou les mock pour votre API
Lors de l'activation du mock service, il est possible d'effectuer directement en ligne de test sur votre api ou grâce à un url mulesoft spécifique directement dans votre application.
Voici par exemple un try-it sur le list défini plus haut :
On voit qu'il est possible de rentrer directement un parameter, ensuite il suffit de cliquer sur GET et voici le résultat :
Il est donc aussi possible d'appeler directement depuis votre application l'url que j'ai flouté :
http://mocksvc.mulesoft.com/mocks/e116b3..62/api-action/list
Et voici un exemple avec un POST qui est ok vis à vis du schéma :
Et un POST en echec vis à vis du schéma :
Autres informations
Pour information :
- Il est possible actuellement de mettre du code HTML dans la description (bien pratique :) )
- Il est possible de faire des imports de fichier, comme ceci :
schema: !include job.xsd - Il existe une spécification pour la sécurité de l'API, cependant, je ne l'ai pas utilisé,donc voici le lien : https://github.com/raml-org/raml-spec/blob/master/08_security.md
- Il est possible et assez facile d'héberger soit même sont propre API Console, voici le lien GITHUB : https://github.com/mulesoft/api-console
- Pour activer les bouchons il faut cliquer sur Mocking Service en haut à droite dans l'API Designer de mulesoft
Voilà, si vous avez des commentaires, des idées, n'hésitez pas :)
Je pense qu'avec ceci, vous êtes prêts pour écrire vos API en RAML.