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 :
-
requestParameters
: contient un résumé des paramètres de la requête en cours (pagination et orderBy), -
uri
: URI d'accès de la collection, -
documents
: un tableau de document (sous la même forme que les documents unitaires)
Chaque document est un objet contenant les entrées suivantes :
-
properties
: liste des propriétés du document, -
attributes
: liste des attributs du document (facultatif), -
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
Raison | Status HTTP | Error Code |
---|---|---|
Sens de l'orderBy inconnu | 400 | CRUD0501 |
Attribut ou propriété d'orderBy invalide | 400 | CRUD0502 |
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'applicationHTTPAPI_V1
(10),
- il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef
-
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
fields | Signification | Remarques |
---|---|---|
document.properties |
Récupère l'ensemble des propriétés par défaut | "id", "title", "icon", "initid", "name" |
document.properties.all |
Récupère toutes les propriétés | |
document.properties.<prop> |
Récupère la propriété indiquée | |
document.attributes.my_attribute |
Ajoute l'attribut my_attribute | si l'attribut n'existe pas dans un des documents il est retourné vide |
requestParameters.slice |
Nombre maximum de document demandé | |
requestParameters.offset |
Nombre de premiers document à ignorer | |
requestParameters.orderBy |
Tri demandé | |
requestParameters.length |
Nombre de document effectivement retourné |
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.