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 :

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.

1.5 Authentification

1.5.1 Authentification par cookie de session

L'accès à l'api requiert une session valide préexistante et préalablement ouverte à l'aide des mécanismes d'authentification de Dynacase (voir manuel de référence de Dynacase Core).

L'api n'est pas utilisable en mode "anonyme" ou "invité".

L'utilisation de l'api dans le cadre d'une interface issue d'une action ne nécessite pas d'autorisation particulière. Le cookie de session est transmis naturellement par le navigateur.

1.5.2 Authentification par jeton d'authentification

L'accès à l'api peut être autorisé à l'aide d'un jeton d'authentification.

Le jeton peut être indiqué dans le header HTTP :

GET api/v1/documents/9.json
Authorization: DcpOpen e2bb65612c70e7ac78d5ccbfe12aa234

Le terme "DcpOpen" est le "HTTP Authentication Scheme" pour identifier le mode d'autorisation.

Il peut être indiqué aussi dans le paramètre GET dcpopen-authorization

GET api/v1/documents/9.json?dcpopen-authorization=e2bb65612c70e7ac78d5ccbfe12aa234

Si un cookie de session est aussi utilisé, il sera ignoré. Le jeton est prioritaire sur le cookie de session.

1.5.2.1 Obtenir un jeton pour l'api

Le jeton d'accès peut être obtenu avec la méthode suivante :

string Dcp\HttpApi\V1\Authent::getAuthorizationToken(
                                    \Account $userAccount,
                                    array    $routes ,
                                    int      $expireDelay = -1, 
                                    bool     $oneshot = false)

Cette méthode retourne un jeton : une chaîne de caractères composée de caractères hexadécimaux (0-9a-f).

$userAccount (Account): Utilisateur identifié pour ce jeton

Les groupes ou rôles ne sont pas autorisés.

$expireDelay (int): Délai de validité du jeton en secondes.

Mettre "-1" (ou false) pour indiquer un délai infini.

$oneshot (bool): Mettre "true" pour indiquer que le jeton sera valide une seule fois

Le jeton est supprimé une fois consommée.

$routes (array): Tableau des routes autorisées

Indique sous forme d'expressions régulières les routes autorisées avec ce jeton la partie /api/v1, ne fait pas partie de la vérification.
De manière facultative, la méthode HTTP (GET, PUT, POST, DELETE) peut préfixer la route afin de limiter à une méthode donnée. Par défaut, les 4 méthodes sont autorisées. Note : un tableau vide n'autorise aucune route.

Une route peut être notée de différentes manières :

• Simple expression régulière
  • %^/documents/[0-9]+(.json)?$%
• Expression régulière plus une méthode
  • PUT %^/documents/[0-9]+(.json)?$%

• Route avec contrainte de paramètre d'url

  [
      "route" => "%^/vendor/my/logs$%",
      "methods" => ["GET"],
      "query" => ["level" => "warning"]
  ]

Dans ce dernier exemple, la route vers les logs de niveau "waring" sera autorisée seulement:

api/v1/vendor/logs?level=warning

1.5.2.2 Exemple de routes

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe"

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken($john, ["%.*%"]);
print $t; // > cad68f8e1848f12df16e44857c595f9a72124f41

Cet exemple autorise toutes les routes à vie pour l'utilisateur "john.doe".

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe" limité aux données de documents.

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken(
    $john, 
    [
      "%^/documents/[0-9]+(.json)?$%",
      "%^/families/[^/]+/[0-9]+(.json)?$%"
    ]);
 

Ici les routes autorisées peuvent être :

• api/v1/documents/1234
• api/v1/documents/5234.json
• api/v1/families/employee/6234.json

Exemple : Construction d'un jeton utilisable à vie pour l'utilisateur "john.doe" limité à la consultation des données de documents.

$john=new account();
$john->setLoginName("john.doe");
 
$t=Dcp\HttpApi\V1\Authent::getAuthorizationToken(
    $john, 
    [
      "GET %^/documents/[0-9]+(.json)?$%",
      "GET %^/families/[^/]+/[0-9]+(.json)?$%"
    ]);
 

1.5.2.3 Utilisation du jeton

En ligne de commande : à l'aide du programme curl :

curl  -H "Authorization: DcpOpen 8e05b60aac3f67447ab4e352a524633839924eda" http://www.example.net/api/v1/documents/12

En ligne de commande : à l'aide du programme wget :

wget http://www.example.net/api/v1/documents/12?dcpopen-authorization=cb713422beb7745f9567710ce011039fabf49224 -O 12.json

Sur un client web en javascript avec jQuery :

var token="8e05b60aac3f67447ab4e352a524633839924eda";
 
$.ajax({
  dataType: "json",
  url: "api/v1/documents/12",
  headers: {
    "Authorization":"DcpOpen " + token
  }
}).done(function (data) {
     console.log("Response", data);
}).fail(function () {
     console.error("Fail", arguments);
});

En PHP :

$token="8e05b60aac3f67447ab4e352a524633839924eda";
$url="http://www.example.net/api/v1/documents/12";
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Authorization: DcpOpen $token\r\n" 
  )
);
 
$context = stream_context_create($opts);
 
$file = file_get_contents($url, false, $context);
print $file;

1.5.3 Authentification par login et mot de passe

Cette authentification est basée sur l'authentification HTTP basic.

L'accès peut être effectué en indiquant le login et le mot de passe dans le header HTTP.

GET api/v1/documents/9.json
Authorization: Basic am9obi5kb2U6c2VjcmV0

Dans ce cas, celui-ci doit contenir la méthode utilisée (Basic) suivi de la représentation en Base64 du nom de l'utilisateur et du mot de passe séparés par le caractère « : » (deux-points).

L'accès peut être effectué via une url comportant le login est le mot passe

• GET http://john.doe:secret@example.net/api/v1/documents/1234

Ce type d'authentification ne comporte pas d'autorisation particulière comme pour les jetons. Toute route est accessible en fonction des droits de l'utilisateur identifié.

Si un cookie de session est aussi utilisé, il sera ignoré. L'utilisation du login et du mot de passe est prioritaire.

Par contre, la requête HTTP contient un header "Authorization" avec la méthode "DcpOpen" et que l'url contient le login et le mot de passe alors, ce sera la méthode "Dcp" qui sera utilisée et non la méthode "Basic".

Note : On ne peut pas avoir 2 headers "Authorization" dans la requête.

1.5.3.1 Utilisation du mode basic

En ligne de commande : à l'aide du programme curl :

Avec les informations en clair :

curl   --user  "john.doe:secret" "http://www.example.net/api/v1/documents/12"
curl   "http://john.doe:secret@www.example.net/api/v1/documents/12"

Note : Dans ce cas curl utilise les informations de connexion pour écrire dans le header la clef "Authorization" avec la méthode "basic" d'authentification. Le programme "wget" ne supporte pas cette notation d'url avec les mots de passe.

Avec les informations encodées.

curl  -H "Authorization: Basic am9obi5kb2U6c2VjcmV0" http://www.example.net/api/v1/documents/12

Sur un client web en javascript avec jQuery :

var login="john.doe";
var password="secret";
 
$.ajax({
  dataType: "json",
  url: "api/v1/documents/12",
  headers: {
    "Authorization":"Basic " + btoa(login + ":" + password)
  }
}).done(function (data) {
     console.log("Response", data);
}).fail(function () {
     console.error("Fail", arguments);
});

En php :

$url="http://john.doe:secret@www.example.net/api/v1/documents/12";
 
$f=file_get_contents($url);
print $f;

Chapitre 2 Historique de la documentation

Ce chapitre contient un descriptif des améliorations entre les releases de l'api HTTP.

2.1 Édition 3

2.2 Édition 2

Chapitre 3 Résumé de l'API

3.1 Carte de l'api

Légende :

• Les URL en italique font références à des collections,
• Les URL en gras font références à des ressources,

Les entrées documents de famillies et de trash possède aussi les sous-collections :

• history,
• revisions.

Les entrées en Future version sont prévues pour une implémentation future mais non présentes dans la version courante de l'API.

Chapitre 4 Documents

Cette collection décrit les documents de Dynacase.

4.1 URL

L'url d'accès est : api/v1/documents

4.2 Méthodes

La collection documents implémente les éléments suivants :

• Collection :

• Ressource :

4.3 Consultation de la liste des documents

4.3.1 URL canonique

GET /api/v1/documents/

Récupération de la liste des documents présents sur la plateforme.

4.3.2 Content

Le contenu de la requête est vide.

4.3.3 Structure de retour

Le retour est une donnée JSON.

4.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. documents : un tableau de document (sous la même forme que les documents unitaires)

Chaque document est un objet contenant les entrées suivantes :

1. properties : liste des propriétés du document,
2. attributes : liste des attributs du document (facultatif),
3. uri : URI d'accès du document.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 10,
            "orderBy": "title asc, id desc"
        },
        "uri": "/api/v1/documents/",
        "documents": [
            {
                "properties": {
                    "id": 1003,
                    "title": "accord",
                    "icon": "api/v1/images/assets/sizes/24x24c/wask.png",
                    "initid": 1003,
                    "name": "WASK",
                    "revision": 0
                },
                "uri": "/api/v1/documents/1003.json"
            },
            [...]
        ]
    }
}

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

4.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

4.3.4 Résultat partiel

4.3.4.1 Pagination et tri

La liste des documents est paginée et ordonnée.

Les mots clefs GET sont les suivants :

• orderBy : <attribut|propriété>:<asc:desc>
  • indique dans quel sens la collection doit être triée, on peut mettre plusieurs valeurs séparées par des ,
  • valeur par défaut : title:asc,
• slice :
  • il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef all,
  • sa valeur par défaut est celle du paramètre applicatif COLLECTION_DEFAULT_SLICE de l'application HTTPAPI_V1 (10),
• offset :
  • indique de passer ce nombre de document avant de renvoyer les documents restants.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

Exemple :

• GET /documents/?orderBy=title:asc,id:desc&slice=100&offset=20

4.3.4.2 Informations retournées

Les documents peuvent être retournés avec plus ou moins d'information.

• GET /documents/?fields=document.properties
• GET /documents/?fields=document.properties.id,document.properties.title

Par défaut : fields=document.properties

La liste des propriétés est documentée dans la documentation de format collection.

4.3.5 Cache

La collection n'a pas de cache.

4.4 Consultation d'un document

4.4.1 URL canonique

GET /api/v1/documents/<documentId>

Récupération de la dernière révision du document ayant l'identifiant <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

GET /api/v1/documents/1234.json

L'identifiant ajouté peut-être soit :

• initid, id de révision, lastid du document,
• name : nom logique du document.

Dans tous les cas le document retourné est le dernier de sa lignée documentaire.

Si vous souhaitez accéder à une révision précise du document, il faut utiliser la collection /api/v1/documents/<documentId>/revisions/.

4.4.2 Content

Le contenu de la requête est vide.

4.4.3 Structure de retour

Le retour est une donnée JSON.

4.4.3.1 En cas de réussite :

La partie data contient 3 champs :

1. document.uri : uri d'accès à la ressource modifiée
2. document.properties : liste des valeurs des propriétés
3. document.attributes : liste des valeurs des attributs

Exemple :

{"success" :             true,
    "messages" :         [],
    "data" :             {
        "document" : {
            "uri" :        "api/v1/documents\/1057.json",
            "properties" : {
                "title" :     "La culture des perles",
                "state" :     null,
                "name" :      null,
                "icon" :      "api/v1/images/assets/sizes/24x24c/doc.png",
                "fromname" :  "MY_ARTICLE",
                [...]
            },
            "attributes" : {
                "my_title" :            {"value" : "La culture des perles", "displayValue" : "La culture des perles"},
                "my_description" :          {"value" : "Sur les bords de la rivière...", "displayValue" : "Sur les bords de la rivière..."},
                "my_annexes" : [],
                [...]
            }
        }
    }
}

Les valeurs retournées correspondent aux valeur de la vue de consultation par défaut.

Les attributs en visibilité "I" dans la vue de consultation par défaut ne sont pas retournés. Leur existence n'est pas dévoilée ni dans les données ni dans la structure.

4.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de document non trouvé

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

4.4.4 Résultat partiel

Le document peut être retourné avec plus ou moins d'information.

• GET /documents/1234.json?fields=document.properties
• GET /documents/1234.json?fields=document.properties.id,document.properties.title,document.attributes
• GET /documents/1234.json?fields=document.properties.id,document.properties.title,document.attributes.my_exemple
• GET /documents/1234.json?fields=document.properties.id,document.properties.title,document.attributes,family.structure

Par défaut : fields=document.properties,document.attributes

La liste des propriétés est documentée dans la documentation de format collection.

4.4.5 Cache

Dans le cadre du cache, le Etag est calculé à l'aide des éléments suivants :

• identifiant du document,
• date de dernière modification,
• identifiant de l'utilisateur,
• identifiant des droits portés sur le document (vecteur de droits),
• langue sélectionnée.

L'ensemble de ces éléments sont concaténés et ensuite le sha1 de cette concaténation consitue le Etag.

4.4.6 Autres URL d'accès

Vous pouvez aussi accéder à cette ressource via :

GET /api/v1/families/<famName>/documents/<documentId>

Récupération de la dernière révision du document de la famille <famName> ayant l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection families/<famName>/documents/ l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

Un document "supprimé" peut être récupéré via l'url trash.

Les documents accédés via les collections families/<famName>/documents/ et trash possèdent aussi les sous- collections :

• history,
• revisions.

4.5 Modification d'un document

4.5.1 URL

PUT /api/v1/documents/<id>

Modification de la dernière révision document ayant l'identifiant <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

PUT /api/v1/documents/1234.json

Attention : L'identifiant du document peut être son nom logique, son identifiant numérique. L'identifiant numérique peut référencer n'importe quelle révision du document. Dans tous les cas, la modification porte sur la dernière révision du document.

4.5.2 Content

4.5.2.1 Format JSON

Le contenu de la requête doit contenir une donnée JSON avec la liste des attributs modifiés.

{
    "document": {
        "attributes": {
            "attrid": {
                "value": "<value>"
            }
        }
    }
}

Le type de la requête est application/json.

Exemple :

{
    "document": {
        "attributes": {
            "my_title": {
                "value": "Hello world"
            }
        }
    }
}

Note : Toute donnée additionnelle sera ignorée.

4.5.2.2 Format urlEncoded

Le contenu de la requête contient la liste des valeurs d'attributs à enregistrer. Chaque variable (PUT) est le nom de l'attribut (casse insensible).

Le type de la requête est application/x-www-form-urlencoded.

Note : Ce format peut être utilisé directement depuis un formulaire HTML.

Cette forme permet aussi d'enregistrer des fichiers dans le document.

4.5.3 Structure de retour

Le retour est une donnée JSON.

4.5.3.1 En cas de réussite :

La partie data contient 3 champs :

1. document.uri : uri d'accès à la ressource modifiée
2. document.properties : liste des valeurs des propriétés
3. document.attributes : liste des valeurs des attributs
4. changes : liste des valeurs modifiées

Exemple :

{"success" :             true,
    "messages" :         [],
    "data" :             {
        "document" : {
            "uri" :        "api\/v1\/documents\/1057.json",
            "properties" : {
                "title" :     "Hello World",
                [...]
            },
            "attributes" : {
                "my_title" :  {"value" : "Hello World", "displayValue" : "Hello World"},
                [...]
            }
        }
    },
    "exceptionMessage" : ""
}

La liste des propriétés est documentée dans la documentation de format collection.

4.5.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

NB : On ne peut pas modifier les documents de familles.

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Update forbidden",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1057\" access deny : Pas de privil\u00e8ge edit pour le document Hello world [1057]"
}

4.5.4 Autres URL d'accès

Vous pouvez aussi accéder à cette ressources via :

PUT /api/v1/families/<famName>/documents/<documentId>

Modification de la dernière révision du document de la famille <famName> ayant l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection families/<famName>/documents/ l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

4.6 Suppression d'un document

4.6.1 URL

DELETE /api/v1/documents/<id>

Suppression de la lignée documentaire dont un des membres a l'identifiant <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

DELETE /api/v1/documents/1234.json

La suppression donne l'ordre de mettre le document dans la poubelle. Dans ce cas, toute la lignée documentaire du document est mise à la poubelle.

L'identifiant du document peut être son nom logique, son identifiant numérique, ou celui de n'importe laquelle de ses révisions.

La suppression "physique" (réelle suppression de la ligne en base de données) n'est pas possible.

4.6.2 Content

Le contenu de la requête est vide.

4.6.3 Structure de retour

Le retour est une donnée JSON.

4.6.3.1 En cas de réussite :

La partie data contient 3 champs :

1. document.uri : uri d'accès à la ressource supprimée;
2. document.properties : liste des valeurs des propriétés du document supprimé;
3. document.attributes : liste des valeurs des attributs du document supprimé.

Les attributs en visibilité "I" ne sont pas retournés. Leur existence n'est pas dévoilée ni dans les données ni dans la structure.

Un document mis à la poubelle n'est plus accessible via la ressource documents mais reste accessible par la ressource trash.

Exemple :

{"success" :             true,
    "messages" :         [],
    "data" :             {
        "document" : {
            "uri" :        "api\/v1\/trash\/1057.json",
            "properties" : {
                "title" :     "La vie des escargots",
                [...]
            },
            "attributes" : {
                "my_title" : {"value" : "La vie des escargots", "displayValue" : "La vie des escargots"},
                [...]
            }
        }
    },
    "exceptionMessage" : ""
}

La liste des propriétés est documentée dans la documentation de format collection.

4.6.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1057\" deleted",
            "contentHtml" : "",
            "code" :        "API0219",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1057\" deleted"
}

4.6.4 Autres URL d'accès

Vous pouvez aussi accéder à cette ressources via :

DELETE /api/v1/families/<famName>/documents/<documentId>

Suppression de la lignée documentaire de la famille <famName> dont un des membres a l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection families/<famName>/documents/ l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

Chapitre 5 Document : Révision

Cette sous-collection décrit les révisions des documents.

5.1 URL

L'url d'accès est : api/v1/documents/<documentId>/revisions/

5.2 Méthodes

La sous-collection revisions implémente les éléments suivants :

• Collection :

• Ressource :

5.3 Consultation de la liste des révisions d'un document

5.3.1 URL

GET /api/v1/documents/<documentId>/revisions/

Récupération de la liste des révisions du document <documentId>.

L'identifiant du document peut être son nom logique, son identifiant numérique.

5.3.2 Content

Le contenu de la requête est vide.

5.3.3 Structure de retour

Le retour est une donnée JSON.

5.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. revisions : un tableau de révision (sous la même forme que les documents unitaires)

Chaque révision est un objet contenant les entrées suivantes :

1. properties : liste des propriétés de la révision,
2. attributes : liste des attributs du document révisé (facultatif),
3. uri : URI d'accès du document.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 2,
            "orderBy": "revision desc, id desc"
        },
        "uri": "http://www.example.net/api/v1/documents/1427/revisions/",
        "revisions": [
            {
                "properties": {
                    "id": 13511,
                    "title": "Éléonore d'aquitaine",
                    "icon": "api/v1/images/assets/sizes/24x24c/article.png",
                    "initid": 1427,
                    "name": null,
                    "status": "alive",
                    "revision": 1
                },
                "attributes": {
                    "an_nom": {
                        "value": "Éléonore d'aquitaine",
                        "displayValue": "Éléonore d'aquitaine"
                    },...
                },
                "uri": "http://www.example.net/api/v1/documents/1427/revisions/1.json"
            },
            {
                "properties": {
                    "id": 1427,
                    "title": "Éléonore",
                    "icon": "api/v1/images/assets/sizes/24x24c/article.png",
                    "initid": 1427,
                    "name": null,
                    "status": "fixed",
                    "revision": 0
                },
                "attributes": {
                    "an_nom": {
                        "value": "Éléonore",
                        "displayValue": "Éléonore"
                    },...
                },
                "uri": "http://www.example.net/api/v1/documents/1427/revisions/0.json"
            }
        ]
    }
}

5.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de document non trouvé

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

5.3.4 Cache

Dans le cadre du cache, le Etag est calculé à l'aide des éléments suivants :

• identifiant de la dernière révision du document,
• date de dernière modification du document,
• identifiant de l'utilisateur,
• identifiant des droits portés sur le document (vecteur de droits),
• langue sélectionnée.

L'ensemble de ces éléments sont concaténés et ensuite le sha1 de cette concaténation consitue le Etag.

5.3.5 Autres URL d'accès

Vous pouvez aussi accéder à cette ressources via :

GET /api/v1/families/<famName>/documents/<documentId>/revisions/

Récupération de la liste des révisions de la dernière révision d'un document de la famille <famName> ayant l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection /api/v1/families/<famName>/documents/<documentId>/revisions/ l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

Les révisions d'un document "supprimé" pevent être récupérés via l'url

GET /api/v1/trash/<documentId>/revisions/

5.4 Consultation d'une révision d'un document

5.4.1 URL

GET /api/v1/documents/<documentId>/revisions/<revisionNumber>

Récupération de la révision <revisionNumber> de la dernière révision d'un document ayant l'id <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

GET /api/v1/documents/1234/revisions/0.json

L'identifiant du document peut être son nom logique, son identifiant numérique.

5.4.2 Content

Le contenu de la requête est vide.

5.4.3 Structure de retour

Le retour est une donnée JSON.

5.4.3.1 En cas de réussite :

La partie data contient 3 champs :

1. revision.uri : uri d'accès à la ressource modifiée
2. revision.properties : liste des valeurs des propriétés
3. revision.attributes : liste des valeurs des attributs

Les attributs en visibilité "I" ne sont pas retournés.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "revision": {
            "properties": {
                "id": 28203,
                "title": "Le monde sous-marin",
                "icon": "api/v1/images/assets/sizes/24x24c/article.gif",
                "initid": 7120,
                "name": null,
                "revision": 17,
                "state": {
                    "reference": "my_transmited",
                    "color": "#A8E5FF",
                    "activity": null,
                    "stateLabel": "Transmis",
                    "displayValue": "Transmis"
                }
            },
            "attributes": {
                "de_reference": {
                    "value": "1",
                    "displayValue": "1"
                },
                "de_version": {
                    "value": "Deuxième",
                    "displayValue": "Deuxième"
                },...
            },
            "uri": "http://www.example.net/api/v1/documents/7120.json"
        }
    }
}

5.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de document non trouvé

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

5.4.4 Résultat partiel

Le document peut être retourné avec plus ou moins d'information.

• GET /documents/1234/revisions/0.json?fields=document.properties
• GET /documents/1234/revisions/0.json?fields=document.properties.status,document.attributes
• GET /documents/1234/revisions/0.json?fields=document.properties.id,document.properties.title,document.attributes.my_exemple
• GET /documents/1234/revisions/0.json?fields=document.properties.id,document.properties.title,document.attributes,family.structure

Par défaut : fields=document.properties,document.attributes

La liste des propriétés est documentée dans la documentation de format collection.

5.4.5 Cache

Dans le cadre du cache, le Etag est calculé à l'aide des éléments suivants :

• id de la révision,
• date de dernière modification,
• identifiant de l'utilisateur,
• identifiant des droits portés sur le document (vecteur de droits),
• langue sélectionnée.

L'ensemble de ces éléments sont concaténés et ensuite le sha1 de cette concaténation consitue le Etag.

5.4.6 Autres URL d'accès

Vous pouvez aussi accéder à cette ressources via :

GET /api/v1/families/<famName>/documents/<documentId>/revisions/<revisionNumber>

Récupération de la révision <revisionNumber> de la dernière révision d'un document de la famille <famName> ayant l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection /api/v1/families/<famName>/documents/<documentId>/revisions/<revisionNumber> l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

La révision d'un document "supprimé" pevent être récupérés via l'url

GET /api/v1/trash/<documentId>/revisions/<revisionNumber>

Chapitre 6 Document : Historique

Cette sous-collection décrit les messages de l'historique des documents

6.1 URL

L'url d'accès est : api/v1/documents/<documentId>/history/

6.2 Méthodes

La sous-collection history implémente les éléments suivants :

• Collection :

• Alternative (restriction sur la famille) :

6.3 Consultation des messages d'historique

6.3.1 URL

GET /api/v1/documents/<documentId>/history/

Récupération de l'historique du document ayant l'identifiant <documentId>.

6.3.2 Content

Le contenu de la requête est vide.

6.3.3 Structure de retour

Le retour est une donnée JSON.

6.3.3.1 En cas de réussite :

La partie data contient les éléments suivants :

Chaque élément de l'historique history contient la structure suivante :

• Un champ properties qui contient :

• Un champ messages qui contient une liste de messages :

Chaque message contient la structure suivante :

Les niveaux (level) correspondent aux criticités suivantes :

Exemple :

GET api/v1/document/7120/history/

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/7120/history/",
        "requestParameters": {
            "slice": -1,
            "offset": 0,
            "revision": -1
        },
        "history": [
            {
                "uri": "http://www.example.net/api/v1/documents/7120/revisions/2.json",
                "properties": {
                    "id": 7120,
                    "title": "Test d'un alligator",
                    "status": "alive",
                    "revision": 2,
                    "owner": {
                        "id": "1",
                        "title": "O'reilly Master"
                    },
                    "state": {
                        "reference": "zoo_transmited",
                        "stateLabel": "Transmis",
                        "activity": "Vérification d'aptitude",
                        "color": "#A8E5FF"
                    },
                    "version": "Deuxième",
                    "revisionDate": "2014-12-01 17:00:37"
                },
                "messages": [
                    {
                        "uid": 1,
                        "uname": "O'reilly Master",
                        "date": "2014-12-01 17:00:37",
                        "level": "info",
                        "code": null,
                        "comment": "no mail template"
                    }
                ]
            },
            {
                "uri": "http://www.example.net/api/v1/documents/7120/revisions/1.json",
                "properties": {
                    "id": 7120,
                    "title": "Test primaire",
                    "status": "fixed",
                    "revision": 1,
                    "owner": {
                        "id": "1",
                        "title": "O'reilly Master"
                    },
                    "state": {
                        "reference": "zoo_accepted",
                        "stateLabel": "Accepté",
                        "activity": "Préparation de l'accueil",
                        "color": "#66FF7A"
                    },
                    "version": null,
                    "revisionDate": "2014-10-16 13:57:16"
                },
                "messages": [
                    {
                        "uid": 1,
                        "uname": "O'reilly Master",
                        "date": "2014-10-16 13:57:16",
                        "level": "message",
                        "code": "REVISION",
                        "comment": "changement d'état de Transmis vers Accepté"
                    },
                    {
                        "uid": 1,
                        "uname": "O'reilly Master",
                        "date": "2014-10-16 13:57:04",
                        "level": "info",
                        "code": null,
                        "comment": "no mail template"
                    }
                ]
            },
            {
                "uri": "http://www.example.net/api/v1/documents/7120/revisions/0.json",
                "properties": {
                    "id": 7120,
                    "title": "Test primaire",
                    "status": "fixed",
                    "revision": 0,
                    "owner": {
                        "id": "1",
                        "title": "O'reilly Master"
                    },
                    "state": {
                        "reference": "zoo_transmited",
                        "stateLabel": "Transmis",
                        "activity": "Vérification de l'adoption",
                        "color": "#A8E5FF"
                    },
                    "version": null,
                    "revisionDate": "2014-10-16 13:57:04"
                },
                "messages": [
                    {
                        "uid": 1,
                        "uname": "O'reilly Master",
                        "date": "2014-10-16 13:57:04",
                        "level": "message",
                        "code": "REVISION",
                        "comment": "changement d'état de Initialisé vers Transmis"
                    },...
                ]
            }
        ]
    }
}

6.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur en cas de document non trouvé

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "Document \"3802\" not found",
            "contentHtml": "",
            "code": "API0200",
            "uri": "",
            "data": null
        },
        {
            "type": "message",
            "contentText": "You can consult http://dynacase.dev:8081/index.php?app=HTTPAPI_V1 to have info on the API",
            "contentHtml": "You can consult <a href=\"http://dynacase.dev:8081/index.php?app=HTTPAPI_V1\">the REST page</a> to have info on the API",
            "code": "",
            "uri": "",
            "data": null
        }
    ],
    "data": null,
    "exceptionMessage": "Document \"3802\" not found"
}

6.3.4 Filtres

6.3.4.1 Slice

Cette option indique le nombre de révision maximum à retourner.

Les révisions sont ordonnées par numéro décroissant, de la plus récente à la plus ancienne.

Exemple : les 10 dernières révisions

GET api/v1/document/1234/history/?slice=10

6.3.4.2 Offset

Index à partir duquel, les révisions sont retournées.

Exemple: Les révisions de 7 à 10.

GET api/v1/document/1234/history/?slice=2&offset=7

6.3.4.3 Révision

Cette option permet de ne retourner l'historique que d'une révision précise.

Exemple : Retourner la révision 3

GET api/v1/document/1234/history/?revision=3

La première révision porte le n°0.

6.3.5 Autres URL d'accès

Vous pouvez aussi accéder à cette ressources via :

GET /api/v1/families/<famName>/documents/<documentId>/history/

Récupération de l'historique de la dernière révision du document de la famille <famName> ayant l'identifiant <documentId>.

La différence entre les collection families et documents est que pour la collection /api/v1/families/<famName>/documents/<documentId>/history/ l'identifiant doit être dans la famille indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

L'historique d'un document "supprimé" peut être récupéré via l'url

GET /api/v1/trash/<documentId>/history/

Chapitre 7 Document : Cycle de vie

Cette collection décrit les états et transitions du cycle de vie associé à un document.

7.1 URL

L'url d'accès est : api/v1/documents/<docid>/workflows/

7.2 Méthodes

La collection documents implémente les éléments suivants :

• Collection :

• Ressource :

7.3 Récupérer les caractéristiques d'un état

7.3.1 URL

GET /api/v1/documents/<documentId>/workflows/states/<stateId>

Récupération de l'état stateId du document documentId.

Exemple :

GET /api/v1/documents/my_document/workflows/states/my_published

7.3.2 Content

Le contenu de la requête est vide.

7.3.3 Structure de retour

Le retour est une donnée JSON.

7.3.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. state : Caractéristique de l'étape
   1. id : identifiant de l'état,
   2. isCurrentState : indique si cet état est l'étape courante,
   3. label : intitulé de l'état (localisé en fonction de la langue de l'utilisateur)
   4. activity : intitulé de l'activité (localisé en fonction de la langue de l'utilisateur)
   5. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
   6. color : code couleur (#RRGGBB) associé à l'état
   7. transition : transition qui emmène à cet étape ("null" si pas de transition possible)
      1. uri : uri de la transition
      2. label : libellé de la transition

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "./api/v1/documents/61120/workflows/states/my_transmited",
        "state": {
            "id": "my_transmited",
            "isCurrentState": false,
            "label": "Transmis",
            "activity": "Vérification de l'adoption",
            "displayValue": "Vérification de l'adoption",
            "color": "#A8E5FF",
            "transition": {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Ttransmited",
                "label": "Transmettre le dossier"
            }
        }
    }
}

7.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

 {
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "State \"foo\" is not available for  workflow \"My workflow\" (1090)",
            "code": "CRUD0228"
        }
    ],
    "data": null,
    "exceptionMessage": "State \"foo\" is not available for  workflow \"My workflow\" (1090)"
}

7.4 Changer d'état

7.4.1 URL

POST /api/v1/documents/<documentId>/workflows/states/<stateid>

Le document documentId passe dans le nouvel état donné stateId. La transition liée à ce changement d'état est exécutée.

Note : Seul l'utilisateur "admin", peut changer l'état d'un document lorsqu'aucune transition n'est valide.

Exemple :

POST /api/v1/documents/<documentId>/workflows/states/<stateid>

7.4.2 Content

Le contenu est une structure JSON qui comprend les informations suivantes :

1. comment : Texte à insérer dans l'historique
2. parameters : Liste des valeurs des paramètres indexés par leur identifiant

Exemple :

{
    "comment" : "Mon commentaire de transition"
    "parameters": {
        "my_referencedate": "2015-06-23",
        "my_validation": "yes"
    }
}

7.4.3 Structure de retour

Le retour est une donnée JSON.

7.4.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. state : Nouvel état du document
   1. id : identifiant de l'état,
   2. isCurrentState : indique si cet état est l'étape courante,
   3. label : intitulé de l'état (localisé en fonction de la langue de l'utilisateur)
   4. activity : intitulé de l'activité (localisé en fonction de la langue de l'utilisateur)
   5. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
   6. color : code couleur (#RRGGBB) associé à l'état

Exemple :

{
    "success": true,
    "messages": [
        {
            "type": "warning",
            "contentText": "Avertissement : Pas de modèle de courriel",
            "code": "WORKFLOW_TRANSITION"
        },
        {
            "type": "notice",
            "contentText": "12:00 - Bulle changement d'état vers Transmis"
        }
    ],
    "data": {
        "state": {
            "id": "my_transmited",
            "isCurrentState": true,
            "label": "Transmis",
            "activity": "Vérification de l'adoption",
            "displayValue": "Vérification de l'adoption",
            "color": "#A8E5FF"
        }
    }
}

7.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "Erreur : Pas d'adresse pour le contrôleur",
            "code": "CRUD0230"
        }
    ],
    "data": null,
    "exceptionMessage": "Cannot use transition \"Erreur : Pas d'adresse pour le contrôleur\" "
}

7.5 Récupérer la liste des étapes

7.5.1 URL

GET /api/v1/documents/<documentId>/workflows/states/

Récupération des étapes suivantes possibles du document documentId.

Les étapes possibles sont les étapes qui ont une transition pour rejoindre l'étape suivante et dont l'utilisateur a les privilège pour passer la transition.

Si la méthode m0 d'une transition, retourne un message, l'étape suivante sera retournée en indiquant l'erreur.

Le paramètre optionnel allStates=1 permet de retourner toutes les étapes même celles qui n'ont pas de transition.

Exemple :

GET /api/v1/documents/my_document/workflows/states/

7.5.2 Content

Le contenu de la requête est vide.

7.5.3 Structure de retour

Le retour est une donnée JSON.

7.5.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. states : Liste des états
   1. id : identifiant de l'état,
   2. label : intitulé de l'état (localisé en fonction de la langue de l'utilisateur)
   3. activity : intitulé de l'activité (localisé en fonction de la langue de l'utilisateur)
   4. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
   5. color : code couleur (#RRGGBB) associé à l'état
   6. uri : URI d'accès à l'état
   7. transition : transition qui emmène à cet étape ("null" si pas de transition possible)
      1. id : identifiant de la transition 1.0.1
      2. uri : uri de la transition
      3. label : libellé de la transition
      4. error : message de la méthode m0
      5. authorized : indique si l'utilisateur possède le droit d'effectuer la transition 1.0.1

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "./api/v1/documents/61120/workflows/states/",
        "states": [
            {
                "id": "my_transmited",
                "label": "Transmis",
                "activity": "Vérification de l'adoption",
                "displayValue": "Vérification de l'adoption",
                "color": "#A8E5FF",
                "uri": "./api/v1/documents/61120/workflows/states/my_transmited",
                "transition": {
                    "id" : "my_Ttransmited",
                    "uri": "./api/v1/documents/61120/workflows/transitions/my_Ttransmited",
                    "label": "Transmettre le dossier",
                    "error": "",
                    "authorized" : true
                }
            }
        ]
    }
}

7.5.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "No associated workflow for document \"9567\"",
            "code": "CRUD0227"
        }
    ],
    "data": null,
    "exceptionMessage": "No associated workflow for document \"9567\""
}

7.6 Récupérer les caractéristiques d'une transition

7.6.1 URL

GET /api/v1/documents/<documentId>/workflows/transitions/<transitionId>

Récupération de la transition transitionId du document documentId.

Exemple :

GET /api/v1/documents/my_document/workflows/transitions/my_publication

7.6.2 Content

Le contenu de la requête est vide.

7.6.3 Structure de retour

Le retour est une donnée JSON.

7.6.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. transition : Caractéristique de la transition
   1. id : identifiant de la transition
   2. beginState : étape de départ de la transition
      1. id : identifiant de l'état de départ
      2. isCurrentState : indique si c'est l'état courant du document
      3. label : libellé de l'état (localisé en fonction de la langue de l'utilisateur)
      4. activity : libellé de l'activité (localisé en fonction de la langue de l'utilisateur)
      5. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
      6. color : code couleur (#RRGGBB) associé à l'état
   3. endState : étape d'arrivée de la transition
      1. id : identifiant de l'état d'arrivée
      2. isCurrentState : indique si c'est l'état courant du document
      3. label : libellé de l'état (localisé en fonction de la langue de l'utilisateur)
      4. activity : libellé de l'activité (localisé en fonction de la langue de l'utilisateur)
      5. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
      6. color : code couleur (#RRGGBB) associé à l'état
   4. label : libellé de la transition (localisé en fonction de la langue de l'utilisateur)
   5. askComment : (bool) indique si un commentaire peut être associé à la transition
   6. askAttributes : liste des paramètres de transition
      1. id : identifiant du paramètre (provenant de la famille du cycle de vie)
      2. visibility : visibilité du paramètre
      3. label : libellé du paramètre
      4. type : type du paramètre
      5. logicalOrder : ordre (non affecté)
      6. multiple : indique si le type est multivalué
      7. options : options de l'attribut
      8. needed : indique si la valeur est obligatoire

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "./api/v1/documents/61120/workflows/transitions/my_Ttransmited",
        "transition": {
            "id": "my_Ttransmited",
            "beginState": {
                "id": "my_initialised",
                "isCurrentState": true,
                "label": "Initialisé",
                "activity": "Rédaction de la demande",
                "displayValue": "Rédaction de la demande",
                "color": "#FFE991"
            },
            "endState": {
                "id": "my_transmited",
                "isCurrentState": false,
                "label": "Transmis",
                "activity": "Vérification de l'adoption",
                "displayValue": "Vérification de l'adoption",
                "color": "#A8E5FF"
            },
            "label": "Transmettre le dossier",
            "askComment": false,
            "askAttributes": [
                {
                    "id": "wan_date",
                    "visibility": "W",
                    "label": "date de début",
                    "type": "date",
                    "logicalOrder": 0,
                    "multiple": false,
                    "options": [],
                    "needed": false
                },
                {
                    "id": "wad_mailsecure",
                    "visibility": "W",
                    "label": "Espèce protégée",
                    "type": "docid",
                    "logicalOrder": 0,
                    "multiple": false,
                    "options": [],
                    "needed": false
                },
                {
                    "id": "wad_file",
                    "visibility": "W",
                    "label": "Fichier",
                    "type": "file",
                    "logicalOrder": 0,
                    "multiple": false,
                    "options": [],
                    "needed": false
                }
            ]
        }
    }
}

7.6.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "transition \"foo\" is not available for  workflow \"My workflow\" (1090)",
            "code": "CRUD0229"
        }
    ],
    "data": null,
    "exceptionMessage": "transition \"foo\" is not available for  workflow \"My workflow\" (1090)"
}

7.7 Passer une transition

7.7.1 URL

POST /api/v1/documents/<documentId>/workflows/transitions/<transitionId>

Le document documentId passe la transition donné transitionId. La transition demandée doit exister à partir de l'état courant.

Exemple :

POST /api/v1/documents/<documentId>/workflows/transitions/my_transmission

7.7.2 Content

Le contenu est une structure JSON qui comprend les informations suivantes :

1. comment : Texte à insérer dans l'historique
2. parameters : Liste des valeurs des paramètres indexés par leur identifiant

Exemple :

{
    "comment" : "Mon commentaire de transition"
    "parameters": {
        "my_referencedate": "2015-06-23",
        "my_validation": "yes"
    }
}

7.7.3 Structure de retour

Le retour est une donnée JSON.

7.7.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. state : Nouvel état du document
   1. id : identifiant de l'état,
   2. isCurrentState : indique si cet état est l'étape courante,
   3. label : intitulé de l'état (localisé en fonction de la langue de l'utilisateur)
   4. activity : intitulé de l'activité (localisé en fonction de la langue de l'utilisateur)
   5. displayValue : intitulé calculé en fonction des valeurs de "activity" et "label"
   6. color : code couleur (#RRGGBB) associé à l'état

Exemple :

{
    "success": true,
    "messages": [
        {
            "type": "warning",
            "contentText": "Avertissement : no mail template",
            "code": "WORKFLOW_TRANSITION"
        },
        {
            "type": "notice",
            "contentText": "13:48 - Bulle changement d'état vers Transmis"
        }
    ],
    "data": {
        "state": {
            "id": "my_transmited",
            "isCurrentState": true,
            "label": "Transmis",
            "activity": "Vérification de l'adoption",
            "displayValue": "Vérification de l'adoption",
            "color": "#A8E5FF"
        }
    }
}

7.7.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

  {
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "Destination state is not defined for workflow \"Défaut demande adoption\" (1090)",
            "code": "CRUD0235"
        },
        {
            "type": "message",
            "contentText": "You can consult ?app=HTTPAPI_V1 to have info on the API",
            "contentHtml": "You can consult <a href=\"?app=HTTPAPI_V1\">the REST page</a> to have info on the API"
        }
    ],
    "data": null,
    "exceptionMessage": "Destination state is not defined for workflow \"Défaut demande adoption\" (1090)"
}

7.8 Récupérer la liste des transitions

7.8.1 URL

GET /api/v1/documents/<documentId>/workflows/transitions/

Récupération de toutes les transitions du document documentId.

Exemple :

GET /api/v1/documents/61120/workflows/transitions/

7.8.2 Content

Le contenu de la requête est vide.

7.8.3 Structure de retour

Le retour est une donnée JSON.

7.8.3.1 En cas de réussite :

La partie data contient :

1. uri : URI préférentielle d'accès à la ressource;
2. transitions : Liste de transition
   1. uri : identifiant de l'état de départ
   2. label : libellé de la transition (localisé en fonction de la langue de l'utilisateur)
   3. valid : indique si la transition existe depuis l'étape courante
      Cela ne vérifie pas si l'utilisateur courant peut passer la transition

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "./api/v1/documents/61120/workflows/transitions/",
        "transitions": [
            {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Ttransmited",
                "label": "Transmettre le dossier",
                "valid": true
            },
            {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Taccepted",
                "label": "Accepter le dossier",
                "valid": false
            },
            {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Trefused",
                "label": "Refuser le dossier",
                "valid": false
            },
            {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Trealised",
                "label": "Fin de traitement",
                "valid": false
            },
            {
                "uri": "./api/v1/documents/61120/workflows/transitions/my_Tretry",
                "label": "À corriger",
                "valid": false
            }
        ]
    }
}

7.8.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "No associated workflow for document \"9567\"",
            "code": "CRUD0227"
        }
    ],
    "data": null,
    "exceptionMessage": "No associated workflow for document \"9567\""
}

Chapitre 8 Document : Supprimé

Cette collection décrit les documents de Dynacase supprimés.

8.1 URL

L'url d'accès est : /api/v1/trash

8.2 Méthodes

La collection trash implémente les éléments suivants :

• Collection : Il n'y a pas d'accès possible directement auprès de la collection :

• Ressource :

8.3 Consultation de la liste des documents supprimés

8.3.1 URL canonique

GET /api/v1/trash/

Récupération de la liste des documents supprimés de la plateforme.

8.3.2 Content

Le contenu de la requête est vide.

8.3.3 Structure de retour

Le retour est une donnée JSON.

8.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. properties : Le titre de la recherche "The trash" (traduit)
4. documents : un tableau de document (sous la même forme que les documents unitaires)

Chaque document est un objet contenant les entrées suivantes :

1. properties : liste des propriétés du document,
2. attributes : liste des attributs du document (facultatif),
3. uri : URI d'accès du document.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 10,
            "orderBy": "title asc, id desc"
        },
        "uri": "/api/v1/trash/",
        "properties": {
            "title": "The trash"
        },
        "documents": [
            {
                "properties": {
                    "id": 1003,
                    "title": "accord",
                    "icon": "api/v1/images/assets/sizes/24x24c/wask.png",
                    "initid": 1003,
                    "name": "WASK",
                    "revision": 0
                },
                "uri": "/api/v1/trash/1003.json"
            },
            [...]
        ]
    }
}

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

8.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

8.3.4 Résultat partiel

8.3.4.1 Pagination et tri

La liste des documents peut être paginée et ordonnée.

Les mots clefs GET sont les suivants :

• orderBy : <attribut|propriété>:<asc:desc>
  • indique dans quel sens la collection doit être triée, on peut mettre plusieurs valeurs séparées par des ,
  • valeur par défaut : title:asc,
• slice :
  • il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef all,
  • sa valeur par défaut est celle du paramètre applicatif COLLECTION_DEFAULT_SLICE de l'application HTTPAPI_V1 (10),
• offset :
  • indique le nombre d'éléments à exclure avant de retourner la collection.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

Exemple :

• GET /trash/?orderBy=title:asc,id:desc&slice=100&offset=20

8.3.4.2 Informations retournées

Les documents peuvent être retournés avec plus ou moins d'information.

• GET /trash/?fields=document.properties
• GET /trash/?fields=document.properties.id,document.properties.title

Par défaut : fields=document.properties

La liste des propriétés est documentée dans la documentation de format collection.

8.3.5 Cache

La collection n'a pas de cache.

8.4 Consultation d'un document supprimé

8.4.1 URL

Récupération d'un document du trash.

GET /api/v1/trash/<documentId>

Récupération de la dernière révision du document supprimé ayant pour id <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

GET /api/v1/trash/1234.json

L'identifiant du document peut être son nom logique, son identifiant numérique.

8.4.2 Content

Le contenu de la requête est vide.

8.4.3 Structure de retour

Le retour est une donnée JSON.

8.4.3.1 En cas de réussite :

La partie data contient 3 champs :

1. document.uri : uri d'accès à la ressource modifiée
2. document.properties : liste des valeurs des propriétés
3. document.attributes : liste des valeurs des attributs

Les attributs en visibilité "I" ne sont pas retournés.

Exemple :

{"success" :             true,
    "messages" :         [],
    "data" :             {
        "document" : {
            "uri" :        "api\/v1\/documents\/1057.json",
            "properties" : {
                "title" :     "Aristote le Stagirite",
                "name" :      null,
                "icon" :      "api/v1/images/assets/sizes/24x24c/doc.png"
                [...]
            },
            "attributes" : {
                "my_title" :            {"value" : "[123", "displayValue" : "[123"},
                "my_level" :          {"value" : 34, "displayValue" : "34"}
                [...]
            }
        }
    }
}

8.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de document non trouvé

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

8.4.4 Résultat partiel

Le document peut être retourné avec plus ou moins d'information.

• GET /api/v1/trash/1234.json?fields=document.properties
• GET /api/v1/trash/1234.json?fields=document.properties.id,document.properties.title,document.attributes
• GET /api/v1/trash/1234.json?fields=document.properties.id,document.properties.title,document.attributes.my_exemple
• GET /api/v1/trash/1234.json?fields=document.properties.id,document.properties.title,document.attributes,family.structure

Par défaut : fields=document.properties,document.attributes

La liste des propriétés est documentée dans la documentation de format collection.

8.5 Restauration d'un document

8.5.1 URL

PUT /api/v1/trash/<id>

Restauration du document <documentId>.

L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple :

PUT /api/v1/trash/1234.json

Attention : L'identifiant du document peut être son nom logique, son identifiant numérique. L'identifiant numérique peut référencer n'importe quelle révision du document. Dans tous les cas, la modification porte sur la dernière révision du document.

8.5.2 Content

8.5.2.1 Format JSON

La demande de restauration doit être formulée de la manière suivante.

Le type de la requête est application/json.

{
    "document": {
        "properties": {
            "status": "alive"
        }
    }
}

Note : Toute donnée additionnelle sera ignorée.

8.5.3 Structure de retour

Le retour est une donnée JSON.

8.5.3.1 En cas de réussite :

La partie data contient 3 champs :

1. document.uri : uri d'accès à la ressource modifiée
2. document.properties : liste des valeurs des propriétés
3. document.attributes : liste des valeurs des attributs

Exemple :

{"success" :             true,
    "messages" :         [],
    "data" :             {
        "document" : {
            "uri" :        "api\/v1\/documents\/1057.json",
            "properties" : {
                "title" :     "Hello World",
                [...]
            },
            "attributes" : {
                "my_title" :  {"value" : "Hello World", "displayValue" : "Hello World"},
                [...]
            }
        }
    },
    "exceptionMessage" : ""
}

8.5.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas de demande de restauration mal formulée

{
    "success": false,
    "messages": [
        {
            "type": "error",
            "contentText": "The restoration must be initialized with {\"document\" : { \"properties\" : { \"status\" : \"alive\" } } }",
            "code": "CRUD0236"
        }
    ],
    "data": null,
    "exceptionMessage": "The restoration must be initialized with {\"document\" : { \"properties\" : { \"status\" : \"alive\" } } }"
}

Chapitre 9 Document : Tags utilisateurs

Cette ressource décrit les tags utilisateur des documents. Un tag est un mot- clef auquel une valeur est éventuellement associée. Ce tag est associé à un document pour un utilisateur particulier.

9.1 URL

L'url d'accès est : api/v1/documents/<documentId>/usertags/

9.2 Méthodes

La sous-collection usertags implémente les éléments suivants :

• Collection :

• Ressource :

9.3 Liste des tags utilisateur

9.3.1 URL

GET /api/v1/documents/<documentId>/usertags/

Récupération des tags de l'utilisateur connecté pour le document documentId.

Exemple :

GET /api/v1/documents/my_document/usertags/

9.3.2 Content

Le contenu de la requête est vide.

9.3.3 Structure de retour

Le retour est une donnée JSON.

9.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination),
2. uri : URI d'accès de la collection,
3. userTags : un tableau de tags utilisateur

Chaque tag utilisateur est un objet contenant les entrées suivantes :

1. id : identifiant du tag (les identifiants sont sensibles à la casse),
2. date : date de pose du tag,
3. value : valeur du tag,
4. uri : URI d'accès au tag.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/34757/usertags/",
        "requestParameters": {
            "slice": -1,
            "offset": 0
        },
        "userTags": [
            {
                "id": "lasttab",
                "date": "2015-01-07 17:40:43",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/lasttab",
                "value": "tst_t_tab_relations"
            },
            {
                "id": "VIEWED",
                "date": "2015-01-07 16:09:13",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/VIEWED",
                "value": ""
            },
            {
                "id": "my_special",
                "date": "2014-12-24 09:21:41",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/solo",
                "value": {
                    "a": 1
                }
            }
        ]
    }
}

9.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

9.3.4 Pagination et tri

La liste des tags utilisateur est paginée et ordonnée.

Les mots clefs GET sont les suivants :

• slice :
  • il indique le nombre maximum de tag à retourner, sa valeur est un entier. Si sa valeur est inférieur ou égale à 0, toutes les valeurs sont retournés,
  • sa valeur par défaut '-1',
• offset :
  • indique de passer ce nombre de tags avant de renvoyer les tags restants.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

Le tri des tags utilisé est basé sur la date de modification. Il est donné dans l'ordre descendant (du plus récent au plus ancien).

Exemple :

• GET /api/v1/documents/my_document/usertags/?slice=10&offset=20

9.4 Récupérer un tag utilisateur

9.4.1 URL

GET /api/v1/documents/<documentId>/usertags/<tagid>

Récupération du tag tagid du document documentId de l'utilisateur connecté.

Exemple :

GET /api/v1/documents/my_document/usertags/my_custom

9.4.2 Content

Le contenu de la requête est vide.

9.4.3 Structure de retour

Le retour est une donnée JSON.

9.4.3.1 En cas de réussite :

La partie data contient 2 champs :

1. uri : URI préférentielle d'accès à la ressource;
2. userTag : Propriétés du tag
   1. id : identifiant du tag (les identifiants sont sensible à la casse),
   2. date : date de pose du tag,
   3. value : valeur du tag. La valeur peut avoir 3 formes :
      1. String : Pour les données chaîne (ex : Hello world)
      2. Numerique : Pour les données numériques (ex : 123.34)
      3. Objet : Pour les données compatibles JSON (ex : {"one": 12, "two":"Hello"})

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/34757/usertags/my_custom",
        "userTag": {
            "id": "my_custom",
            "date": "2014-12-24 09:17:24",
            "value": {
                "my_first": 1123,
                "my_second": "Hello world"
            }
        }
    }
}

9.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

9.5 Créer un tag utilisateur

9.5.1 URL

POST /api/v1/documents/<documentId>/usertags/<tagid>

Création du tag tagid pour document documentId. Le tag est associé à l'utilisateur connecté.

Exemple :

POST /api/v1/documents/my_document/usertags/my_custom

Le droit de modifier le document n'est pas requis pour ajouter un tag. Seul le droit de consulter le document est requis.

9.5.2 Content

Le contenu contient la valeur du tag. Si elle est vide la valeur sera égale à la chaîne vide.

Si le contenu est une structure json, la valeur retournée sera une structure.

9.5.3 Structure de retour

Le retour est une donnée JSON.

9.5.3.1 En cas de réussite :

La partie data contient 2 champs :

1. uri : URI préférentielle d'accès à la ressource;
2. userTag : liste des valeurs des propriétés;

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/34757/usertags/test",
        "userTag": {
            "id": "test",
            "date": "2015-01-08 14:58:27",
            "value": "Hello"
        }
    }
}

9.5.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

9.6 Modifier un tag utilisateur

9.6.1 URL

PUT /api/v1/documents/<documentId>/usertags/<tagid>

Modification du tag tagid du document documentId pour l'utilisateur connecté.

Exemple :

PUT /api/v1/documents/my_document/usertags/my_custom

Si le tag n'existe déjà, il est créé.

9.6.2 Content

Le contenu contient la valeur du tag.
Si il est vide la valeur est égale à la chaîne vide.

Si le contenu est une structure JSON, la valeur retournée est une structure.

9.6.3 Structure de retour

Le retour est une donnée JSON.

9.6.3.1 En cas de réussite :

La partie data contient 2 champs :

1. uri : URI préférentielle d'accès à la ressource;
2. userTag : liste des valeurs du tag;

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/34757/usertags/test",
        "userTag": {
            "id": "test",
            "date": "2015-01-08 14:58:27",
            "value": {
                "first":"Interesting",
                "second" : 123.56
            }
        }
    }
}

9.6.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

9.7 Supprimer un tag utilisateur

9.7.1 URL

DELETE /api/v1/documents/<documentId>/usertags/<tagid>

Suppression du tag tagid du document documentId

Exemple :

DELETE /api/v1/documents/my_document/usertags/my_custom

Le droit de modifier le document n'est pas requis pour supprimer un tag. Seul le droit de consulter le document est requis.

9.7.2 Content

Le contenu de la requête est vide.

9.7.3 Structure de retour

Le retour est une donnée JSON.

9.7.3.1 En cas de réussite :

La partie data est vide.

Exemple :

{
    "success": true,
    "messages": [],
    "data": null
}

9.7.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

Chapitre 10 Recherche

Cette collection décrit les recherches de Dynacase.

10.1 URL

L'url d'accès est : api/v1/searches

10.2 Méthodes

La collection searches implémente les éléments suivants :

• Collection : Il n'y a pas d'accès possible directement auprès de la collection :

Une recherche étant un document Dynacase, la création d'une nouvelle recherche passe par l'utilisation de l'entrée families/SEARCH/documents/. De plus, il existe différents type de recherches.

• Ressource :

10.3 Liste des recherches

10.3.1 URL canonique

GET /api/v1/searches/

Récupération de la liste des recherches accessibles.

10.3.2 Content

Le contenu de la requête est vide.

10.3.3 Structure de retour

Le retour est une donnée JSON.

10.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. documents : un tableau de recherche (sous la même forme que les documents unitaires)

Chaque document est un objet contenant les entrées suivantes :

1. properties : liste des propriétés de la recherche,
2. uri : URI de contenu de la recherche.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 9,
            "orderBy": "title asc, id desc"
        },
        "uri": "/api/v1/searches/",
        "documents": [
            {
                "properties": {
                    "id": 1894,
                    "title": "Les articles intéressants",
                    "icon": "api/v1/images/assets/sizes/24x24c/search.gif",
                    "initid": 1894,
                    "name": null,
                    "revision": 0
                },
                "uri": "/api/v1/searches/1894/documents/"
            }[...]
        ]
    }
}

10.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

10.3.4 Résultat partiel

10.3.4.1 Pagination et tri

La liste des documents peut être paginée et ordonnée.

Les mots clefs GET sont les suivants :

• orderBy : <attribut|propriété>:<asc:desc>
  • il indique dans quel sens la collection doit être triée,
  • valeur par défaut : title:asc,
• slice :
  • il indique le nombre maximum de documents à retourner,
  • sa valeur par défaut est celle du paramètre applicatif COLLECTION_DEFAULT_SLICE de l'application HTTPAPI_V1 (10),
• offset :
  • il indique le nombre d'éléments à exclure avant de retourner la collection.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

10.3.4.2 Informations retournées

Les documents peuvent être retournés avec plus ou moins d'information.

• GET /searches/?fields=document.properties
• GET /searches/?fields=document.properties.id,document.properties.title

Par défaut : fields=document.properties

La liste des propriétés est documentée dans la documentation de format collection.

10.3.5 Cache

La collection n'a pas de cache.

10.4 Consultation du contenu d'une recherche

10.4.1 URL canonique

GET /api/v1/searches/<searchId>/documents/

Récupération de la liste des documents trouvés par la recherche <searchId>.

10.4.2 Content

Le contenu de la requête est vide.

10.4.3 Structure de retour

Le retour est une donnée JSON.

10.4.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. properties: contient le titre de la recherche, et l'uri d'accès au document "recherche"
4. documents : un tableau de document (sous la même forme que les documents unitaires)

Chaque document est un objet contenant les entrées suivantes :

1. properties : liste des propriétés du document,
2. attributes : liste des attributs du document (facultatif),
3. uri : URI d'accès du document.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 1,
            "orderBy": "title asc, id desc"
        },
        "uri": "http://www.example.net/api/v1/searches/5236/documents/",
        "properties": {
            "title": "Articles intéressants",
            "uri": "http://localhost/tmp32/api/v1/document/5236.json"
        },
        "documents": [
            {
                "properties": {
                    "id": 26653,
                    "title": "La culture des perles",
                    "icon": "api/v1/images/assets/sizes/24x24c/article.png",
                    "initid": 1425,
                    "name": null,
                    "revision": 1
                },
                "uri": "http://www.example.net/api/v1/documents/1425.json"
            }
        ]
    }
}

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

10.4.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

10.4.4 Résultat partiel

10.4.4.1 Pagination et tri

La liste des documents peut être paginée et ordonnée.

Les mots clefs GET sont les suivants :

• orderBy : <attribut|propriété>:<asc:desc>
  • indique dans quel sens la collection doit être triée, on peut mettre plusieurs valeurs séparées par des ,
  • valeur par défaut : title:asc,
• slice :
  • il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef all,
  • sa valeur par défaut est celle du paramètre applicatif COLLECTION_DEFAULT_SLICE de l'application HTTPAPI_V1 (10),
• offset :
  • indique le nombre d'éléments à exclure avant de retourner la collection.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

Exemple :

• GET /searches/<my_search>/?orderBy=title:asc,id:desc&slice=100&offset=20

10.4.4.2 Informations retournées

Les documents peuvent être retournés avec plus ou moins d'information.

• GET /searches/<my_search>/documents/?fields=document.properties
• GET /searches/<my_search>/documents/?fields=document.properties.id,document.properties.title
• GET /searches/<my_search>/documents/?fields=document.properties.id,document.properties.title
• GET /searches/<my_search>/documents/?fields=document.attributes
• GET /searches/<my_search>/documents/?fields=document.attributes.my_attribute

Par défaut : fields=document.properties

La liste des propriétés est documentée dans la documentation de format collection.

10.4.5 Cache

La collection n'a pas de cache.

Chapitre 11 Dossier

Cette collection décrit les dossiers de Dynacase.

Un dossier est un document permettant de stocker un ensemble de documents.

11.1 URL

L'url d'accès est : /api/v1/folders

11.2 Méthodes

La collection searches implémente les éléments suivants :

• Collection : Il n'y a pas d'accès possible directement auprès de la collection :

Une recherche étant un document Dynacase, la création d'une nouvelle dossier passe par l'utilisation de l'entrée families/DIR/documents/.

• Ressource :

11.3 Liste des dossiers

11.3.1 URL canonique

GET /api/v1/folders/

Récupération de la liste des dossiers accessibles.

11.3.2 Content

Le contenu de la requête est vide.

11.3.3 Structure de retour

Le retour est une donnée JSON.

11.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination et orderBy),
2. uri : URI d'accès de la collection,
3. documents : un tableau de document (sous la même forme que les documents unitaires)

Chaque document est un objet contenant les entrées suivantes :

1. properties : liste des propriétés du dossier,
2. uri : URI du contenu du dossier

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 10,
            "orderBy": "title asc, id desc"
        },
        "uri": "/api/v1/folders/",
        "properties": {
            "title": "The folders"
        },
        "documents": [
            {
                "properties": {
                    "id": 1011,
                    "title": "Administrateurs",
                    "icon": "api/v1/images/assets/sizes/24x24c/igroup.png",
                    "initid": 1011,
                    "name": "GADMIN",
                    "revision": 0
                },
                "uri": "/api/v1/folders/1011/documents/"
            }
        ], ...
    }
}