API REST

API REST

Présentation

L'API HTTP a pour but d'offrir un accès standard aux données de Anakeen Platform.
L'architecture de cette api s'appuie sur une architecture REST(Representational State Transfer) et permet de manipuler les ressources Anakeen Platform suivantes:

• Smart Structure,
• Smart Element,
• Files.

Quelques notions de REST

L'API présentée est de type REST et utilise le vocabulaire propre à ces API, ce qui inclut:

• ressource: une ressource est un type de donnée et son contenu; dans notre cas un Smart Element, la description d'un fichier, etc... ,
• collection: une collection est un type de ressource. Dans notre cas, la liste des Smart Elements, la liste des fichiers, etc. La collection est utilisée pour référencer une ressource, créer une ressource, détruire une ressource,
• identifiant: l'identifiant est la clef unique permettant de trouver une ressource au sein d'une collection. Dans notre cas, c'est l'id d'un Smart Element, d'un fichier, etc.

Structure de l'API

La structure est conforme au standard REST. Les actions du CRUD sont implémentées et associées aux méthodes de HTTP, suivant la liste d'équivalence suivante:

Action	Méthode HTTP	URL	Action effectuée
Create	POST	/api/v2/<collection>	Créé une nouvelle ressource dans la collection et répond avec la ressource
Read	GET	/api/v2/<collection>	Lit le contenu de la collection et répond avec une liste de ressources
Read	GET	/api/v2/<collection>/<id>	Lit la ressource id et répond avec la ressource
Update	PUT	/api/v2/<collection>	Remplace l'intégralité de la collection et répond avec une liste de ressources
Update	PUT	/api/v2/<collection>/<id>	Modifie la ressource id de la collection et répond avec la ressource
Delete	DELETE	/api/v2/<collection>	Supprime l'intégralité de la collection et répond avec une liste de ressources
Delete	DELETE	/api/v2/<collection>/<id>	Supprime la ressource id de la collection et répond avec la ressource

Les accès à l'API HTTP Anakeen Platform se font par l'URL: http://<url_du_contexte>/api/v2/.

Encodage

Tous les échanges, entrées et retours de l'API, sont encodés en UTF-8.

Requête

Les éléments de la requête sont les suivants;

Type de retour attendu

Le type de retour attendu (format) est précisé soit:

• dans l'URL: PUT /api/v2/<collection>/<identifier>.<type>,
• dans l'entête HTTP: accept

Actuellement, seul le type json est géré. Celui-ci est renvoyé dans le corps de la requête HTTP.
Le type exprimé dans l'URL est prioritaire à celui de l'entête HTTP.
Pour supporter certains navigateurs ne possédant pas les objets XMLHttpRequest v2, il est possible d'ajouter le paramètre GET alt=html et d'avoir ainsi le retour de la donnée JSON dans un textarea au sein d'une page web.

PUT (mise à jour), POST (création)

Les données à enregistrer dans la ressource peuvent être envoyées sous 2 formes:

• Sous la forme d'un objet JSON (application/json) transmis dans le corps de la requête HTTP,
• Sous la forme de variables encodées (x-www-from-urlencoded) transmises dans le code de la requête HTTP.

Les options de mise à jour sont envoyées via des variables sur l'URL.

GET (consultation), DELETE (suppression)

Le corps de la requête est vide.
Les options de consultation, suppression sont envoyées dans l'URL à l'aide de variables dans l'URL.
Exemples:

• consultation du Smart Element 1234: GET /api/v2/smart-elements/1234.json,
• suppression du Smart Element DEVPERSON_JEAN_REMI: DELETE /api/v2/smart-elements/DEVPERSON_JEAN_REMI

Compatibilité

Certains clients ne permettant pas d'effectuer des requêtes autre que GET et POST, un fonctionnement en mode compatibilité est possible. Pour ce faire, il faut modifier l'entête HTTP en ajoutant X-HTTP-Method-Override:

• Simuler une méthode PUT: POST X-HTTP-Method-Override: PUT,
• Simuler une méthode DELETE: POST X-HTTP-Method-Override: DELETE.

Réponse

L'API répond via plusieurs éléments: le contenu (content) du retour et les entêtes (header) HTTP.

Contenu

Dans le cas dun retour JSON, la structure retournée contient les éléments suivants:

{
  "success": true, // false ou true
  "messages": [
    {
      "type": "warning", // type de message error, userMessage, warning, notice, notification
      "contentText": "once upon a time",
      "contentHtml": "",
      "code": "", // code identifiant la catégorie du message
      "uri": "", // URL d'accès à la page web correspondant à l'erreur
      "data": {} // données supplémentaires
    }
  ],
  "data": {} // données demandées par la requête
}

Ce retour est envoyé quelque soit le résultat de la requête, y compris en cas d'erreur.

Code de retour HTTP

L'API utilise les codes standards du protocole HTTP.

Les retours sans erreur

Si l'action demandée a été exécutée, le code HTTP 2xx est retourné:

• 200 : ressource trouvée,
• 201 : ressource créé.

Exemple de retour:

{
  "success": true,
  "data": {
    "document": {
      "properties": {
        "id": 98147,
        "title": "Bill 0039 BIDART Andréa",
        "initid": 98147,
        "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
        "name": null,
        "revision": 0,
        "status": "deleted"
      },
      "attributes": {
        "bill_title": {
          "value": "Bill 0039",
          "displayValue": "Bill 0039"
        }
      }
    }
  }
}

Dans l'enveloppe retournée, le booléen success est à true?

Les retours d'erreurs

Si l'action demandée n'a pas pu aboutir, un code HTTP 4xx ou 5xx est retourné:

• 400: données en entrée invalides,
• 403: ressource protégée (accès interdit),
• 404: ressource non trouvée,
• 501: la méthode demandée n'est pas disponible sur cette ressource,
• 507: espace de stockage insuffisant sur le serveur.

Version de l'API

Il est nécessaire de préciser la version de l'API pour s'assurer de l'immuabilité des retours et des entrées.
La version de l'API doit être indiquée dans l'URL: /api/v2/smart-elements/1234.json.
La version de l'API est le chiffre indiqué après la lettre v.

Droit d'accès

L'accès aux ressources est contrôlé par les ressources elles-même mais l'utilisation de l'API est aussi contrôlée de manière générale par l'application HTTPAPI.
Cette application définit 4 droits (ACL) qui autorisent l'utilisation des méthodes sur les ressources/collections:

• PUT,
• POST,
• GET,
• DELETE. Ces droits s'appliquent de manière globale sur toute l'API quelque soit la ressource/collection concernée. Si un utilisateur ne possède pas le droit, il ne peut pas effectuer de demande de ce type.
  L'accès aux routes est contrôlé si la configuration de la route indique un droit spécifique.