Chapitre 1 API HTTP REST

1.1 Présentation

L'API HTTP a pour but d'offrir un accès standard aux données de Dynacase.

L'architecture de cette api s'appuie sur une architecture REST (Representational state transfer) et permet de manipuler les ressources Dynacase suivantes :

  • les documents,
  • les familles,
  • les fichiers.

1.2 Quelques notions de REST

L'api présentée dans la suite du document 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 document, la description d'un fichier, etc.,
  • collection : une collection est un type de ressource. Dans notre cas, la liste des documents, 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 document, le vaultid d'un fichier, etc.

1.3 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/v1/<collection> Créé une nouvelle ressource dans la collection et répond avec la ressource
Read GET /api/v1/<collection> Lit le contenu de la collection et répond avec une liste de ressources
Read GET /api/v1/<collection>/<id> Lit la ressource id et répond avec la ressource
Update PUT /api/v1/<collection> Remplace l'intégralité de la collection et répond avec une liste de ressources
Update PUT /api/v1/<collection>/<id> Modifie la ressource id de la collection et répond avec la ressource
Delete DELETE /api/v1/<collection> Supprime l'intégralité de la collection et répond avec une liste de ressources
Delete DELETE /api/v1/<collection>/<id> Supprime la ressource id de la collection et répond avec la ressource

Les accès à l'API HTTP Dynacase se font par l'url http[s]://<url_du_contexte>/api/v1/.

1.3.1 Encodage

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

1.3.2 Requête

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

1.3.2.1 Type de retour attendu

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

  • dans l'URL
    [http]
    PUT /api/v1/<collection>/<identifier>.<type>
  • dans le header 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 du header 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. 1.0.1

1.3.2.2 PUT (Mise à jour), POST (Création)

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

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

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

1.3.2.3 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 document 212 : GET : /api/v1/documents/212
  • Suppression du document IUSER_JEAN_REMI : DELETE : /api/v1/documents/IUSER_JEAN_REMI

1.3.2.4 Compatibilité

Certains clients ne permettant pas d'effectuer des requêtes autre que GET et POST, un fonctionnement en mode compatiblité est possible. Pour ce faire, il faut modifier le header 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

1.3.3 Réponse

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

1.3.3.1 Contenu

Dans le cas d'un 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.

1.3.3.2 Code de retour http

L'API utilise les codes standards du protocole HTTP.

1.3.3.2.1 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, // false ou true
    "messages" : [],
    "data" : {
        "document" : {
                "properties" : {
                    "id" : 1224,
                    "title" : "Hello world"
                },
                "attributes" : {
                    "ba_ttle" : {"value" : "Hello world"},
                    "ba_desc" : {"value" : "Nice Day"},
                }
          }
    }
}

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

1.3.3.2.2 Les retours d'erreur

Si l'action demandée n'a pas pu aboutir, un code HTTP 4xx ou en 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

Exemple de retour, cas d'un 404 :

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"22222\" not found",
            "contentHtml" : "",
            "code" :        "API0200",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"22222\" not found"
}

Dans l'enveloppe retournée, le booléen success est à false est un ensemble de messages explicitant l'erreur est ajouté dans le tableau messages.

1.3.4 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/v1/documents/1234.json

La version de l'api est le chiffre indiqué après la lettre "v".

1.4 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.

Source : intro.md Dynacase Platform 3.2 | API HTTP Core Manuel de référence, version 1.0 édition 3, © Anakeen Labs <labs@anakeen.com>
×
Publié sous licence CC (http://creativecommons.org/licenses/by-nc-sa/2.0/fr/) par Anakeen [www.anakeen.com]
Attribution Vous devez créditer l'Oeuvre, intégrer un lien vers la licence et indiquer si des modifications ont été effectuées à l'Oeuvre. Vous devez indiquer ces informations par tous les moyens possibles mais vous ne pouvez pas suggérer que l'Offrant vous soutient ou soutient la façon dont vous avez utilisé son Oeuvre.
Pas d’Utilisation Commerciale Vous n'êtes pas autoriser à faire un usage commercial de cette Oeuvre, tout ou partie du matériel la composant.
Partage dans les Mêmes Conditions Dans le cas où vous effectuez un remix, que vous transformez, ou créez à partir du matériel composant l'Oeuvre originale, vous devez diffuser l'Oeuvre modifiée dans les même conditions, c'est à dire avec la même licence avec laquelle l'Oeuvre originale a été diffusée.