« Back
in API RAML read.

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 :
Rendu API 1

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 :

Rendu API 2

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 :

alt

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.

comments powered by Disqus