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, levaultid
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 :
- 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-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.