API HTTP REST : Manuel de référence | API HTTP Core

link管理

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

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 :


   /api/v1/<collection>

Créé une nouvelle ressource dans la collection et répond avec la ressource


   /api/v1/<collection>

Lit le contenu de la collection et répond avec une liste de ressources


   /api/v1/<collection>/<id>

Lit la ressource

id

et répond avec la ressource


   Update


   /api/v1/<collection>

Remplace l'intégralité de la collection et répond avec une liste de ressources


   Update


   /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

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

Ressource trouvée

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

Données en entrée invalides

Ressource protégée (accès interdit)

Ressource non trouvée

La méthode demandée n'est pas disponible sur cette ressource

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 <[email protected]>

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.