RAML: un linguaggio per la documentazione delle API

RAML: un linguaggio per la documentazione delle API

In questi giorni sono entrato in contatto con RAML, un linguaggio di programmazione creato per documentare in maniera efficace le proprie API.

Difatti sto partecipando all’APIConUK, una conferenza di tre giorni incentrata sul mondo delle API. Tra i moltissimi talk interessanti (le giornate sono molto intense: ben cinque ogni giorno), uno in particolare ha colpito la mia attenzione… e il caso ha voluto che quello dedicato a RAML fosse proprio il primo.

Con RAML è possibile non solo documentare le proprie API, ma anche usare alcuni tool scritti in JavaScript e NodeJS e rilasciati in modalità OpenSource che permettono all’utilizzatore delle API di accedere ad una documentazione interattiva e testare in realtime il funzionamento senza dover accedere attraverso tools generici come REST Console o, addirittura, CURL.

L’editor API per lo sviluppatore delle API, la console e il notebook dedicati all’utilizzatore delle API, possono essere utilizzate anche senza installare nulla sui propri server, sfruttando una installazione pubblica messa a disposizione da MuleSoft.

La sintassi di RAML è molto simile a YAML, per cui è davvero semplice ed intuitivo scrivere la propria documentazione delle API e la documentazione presente sul sito web ufficiale e davvero completa ed intuitiva.

Sostanzialmente, si parte con gli header:

#%RAML 0.8
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1
Per poi passare ad elencare le risorse a cui rispondono le proprie API con eventuali risorse interne. As esempio:
 /users:
/authors:
  /{authorname}:
/books:

Quindi si passa ad elencare i metodi utilizzabili in ciascuna risorsa, sempre utilizzando l’indentazione come su YAML:

/books:
   get:
   put:
   post:
   /{bookTitle}:
     get:
     put:
     delete:
     /author:
       get:
     /publisher:
       get:

Siamo quasi alla fine; si inseriscono gli i parametri da passare a ciascun metodo:

 /books:
   /{bookTitle}
     get:
       queryParameters:
         author:
         publicationYear:
         rating:
         isbn:
     put:
       queryParameters:
         access_token:

completandoli con gli attributi per ciascun parametro:

/books:
   /{bookTitle}
     get:
       queryParameters:
         author:
           displayName: Author
           type: string
           description: An author's full name
           example: Mary Roach
           required: false
         publicationYear:
           displayName: Pub Year
           type: number
           description: The year released for the first time in the US
           example: 1984
           required: false
         rating:
           displayName: Rating
           type: number
           description: Average rating (1-5) submitted by users
           example: 3.14
           required: false
         isbn:
           displayName: ISBN
           type: string
           minLength: 10
           example: 0321736079?
      put:
        queryParameters:
          access_token:
            displayName: Access Token
            type: string
            description: Token giving you permission to make call
            required: true

Infine, ora che abbiamo descritto in maniera approfondita le chiamate, facciamo altrettanto con le risposte:

/books:
   /{bookTitle}:
     get:
       description: Retrieve a specific book title
       responses:
         200:
           body:
             application/json:
              example: |
                 {
                   "data": {
                     "id": "SbBGk",
                     "title": "Stiff: The Curious Lives of Human Cadavers",
                     "description": null,
                     "datetime": 1341533193,
                     "genre": "science",
                     "author": "Mary Roach",
                     "link": "http://e-bookmobile.com/books/Stiff",
                   },
                   "success": true,
                   "status": 200
                 }

A questo punto il file con la documentazione delle API è pronto e non ci resta altro da fare che renderlo fruibile ai nostri utenti attraverso i tool a cui abbiamo fatto cenno poc’anzi.

Leave a Reply

Your email address will not be published. Required fields are marked *

9 − 6 =