12.4 Consultation des documents de la familles
12.4.1 URL canonique
GET /api/v1/families/<famName>/documents/
Récupération de la liste des documents de la famille families
présents sur la plateforme.
12.4.2 Content
Le contenu de la requête est vide.
12.4.3 Structure de retour
Le retour est une donnée JSON.
12.4.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, -
properties
: titre de la recherche (composée à partie du titre de la famille) -
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": 2, "orderBy": "title asc, id desc" }, "uri": "/api/v1/families/TEXT/documents/", "properties": { "title": "Texte Documents" }, "documents": [ { "properties": { "id": 1054, "title": "La vie des fourmis", "icon": "api/v1/images/assets/sizes/24x24c/text.gif", "initid": 1054, "name": null, "revision": 0 }, "uri": "/api/v1/documents/1054.json" }, { "properties": { "id": 1053, "title": "Les grands philosophes", "icon": "api/v1/images/assets/sizes/24x24c/text.gif", "initid": 1053, "name": null, "revision": 0 }, "uri": "/api/v1/documents/1053.json" } ] } }
Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.
12.4.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 |
12.4.4 Résultat partiel
12.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'applicationHTTPAPI_V1
(10),
- il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef
-
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
families/<famName>/documents/?orderBy=title:asc,id:desc&slice=100&offset=20
12.4.4.2 Informations retournées
Les documents peuvent être retournés avec plus ou moins d'information.
- GET
families/<famName>/documents/?fields=document.properties
- GET
families/<famName>/documents/?fields=document.properties.id,document.properties.title
Par défaut : fields=document.properties
fields | Signification | Remarques |
---|---|---|
document.properties |
Récupère les propriétés données par défaut | "id", "title", "icon", "initid", "name", "revision" |
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 |
document.attributes |
Ajoute tous les attributs |
La liste des propriétés est documentée dans la documentation de format collection.
12.4.5 Cache
La collection n'a pas de cache.