Conventions pour l'API

Le principe de base de toute API est de faciliter le dialogue et la transmission d'information entre deux applications. Une API est tout simplement un lot d'URL utilisables facilement depuis un programme, quel qu'il soit.

Pour faciliter ce dialogue entre machines, il est essentiel que chacun suive les mêmes conventions.

Avant de nous lancer dans la mise en pratique, il faut fonc que l'on aborde les deux standards utilisés par EtuUTT pour la transmission de données : REST et JSON.

REST

REST est une méthode d'organisation d'URL pour API. REST fournit en quelque sorte le squelette de l'API.

La méthode REST est très liée au protocole HTTP et essaie de l'utiliser au maximum de ses possibilités : le but est de décrire des ressources par des URL et d'utiliser les méthodes HTTP comme des actions sur ces ressources. Par exemple :

.. code:: http

  GET   /users/1       Retourne les informations sur l'utilisateur d'identifiant 1
 POST   /users         Créer un utilisateur
  PUT   /users/1       Modifie l'utilisateur d'identifiant 1

DELETE /users/1 Supprime l'utilisateur d'identifiant 1

De cette manière, les URL sont cohérentes et simples d'utilisation. C'est cette convention que l'API d'EtuUTT suit pour ses URL.

.. note::

Pour en savoir plus sur REST :

http://fr.wikipedia.org/wiki/Representational_State_Transfer
http://www.figer.com/Publications/REST.htm#.U9kPu_l_tOY

JSON

JSON est un format de données. Là où REST est le squelette de l'API, JSON est sa langue. C'est un format standard, inter-languages, qui permet de partager des données facilement entre machines.

Il est très comparable à XML, si ce n'est qu'il est beaucoup moins verbeux et plus facile à lire à l'oeil humain.

Il existe des décodeurs JSON dans presque tous les languages de programmations, à vous de trouver le vôtre (le décodeur JSON est natif dnas beaucoup de languages) !

.. note::

Pour en savoir plus sur JSON :

http://fr.wikipedia.org/wiki/JavaScript_Object_Notation
http://json.org/

.. note::

Toutes les réponses de l'API d'EtuUTT auront ce format :

.. code:: json

    {
        "http": {
            "status": <status_code>,
            "message": "<status_message>"
        },
        "response": <reponse_data>
    }

Il vous est donc très simple de vérifier qu'une requête n'a pas échoué.