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 :
-
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
: contient le titre de la recherche, et l'uri d'accès au document "recherche" -
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": 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
Raison | Status HTTP | Error Code |
---|---|---|
Sens de l'orderBy inconnu | 400 | CRUD0501 |
Attribut ou propriété d'orderBy invalide | 400 | CRUD0502 |
L'identifiant de la recherche ne correspond pas à une recherche | 400 | CRUD0503 |
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'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
/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
fields | Signification | Remarques |
---|---|---|
document.properties |
Récupère l'ensemble des propriétés 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 |
Ajoute tous les attributs de la famille référencée par la recherche | s'il n'y a pas de famille de référence alors aucun attribut n'est retourné |
document.attributes.my_attribute |
Ajoute l'attribut my_attribute | si l'attribut n'existe pas dans un des documents il est retourné vide |
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.