11.4 Consultation du contenu d'un dossier

11.4.1 URL canonique

GET /api/v1/folders/<folderId>/documents/

Récupération de la liste des documents contenu par le dossier <folderId>.

11.4.2 Content

Le contenu de la requête est vide.

11.4.3 Structure de retour

Le retour est une donnée JSON.

11.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. documents : un tableau de documents (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 au document

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "requestParameters": {
            "slice": 10,
            "offset": 0,
            "length": 10,
            "orderBy": "title asc, id desc"
        },
        "uri": "/api/v1/folders/9987/documents/",
        "properties": {
            "title": "Documents importants",
            "uri": "http://www.example.net/api/v1/documents/9987.json"
        },
        "documents": [
            {
                "properties": {
                    "id": 1003,
                    "title": "Réchauffement climatique",
                    "icon": "api/v1/images/assets/sizes/24x24c/article.png",
                    "initid": 1003,
                    "name": null,
                    "revision": 0
                },
                "uri": "http://www.example.net/api/v1/documents/1003.json"
            },
            [...]
        ]
    }
}

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

11.4.3.2 En cas d'échec

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

11.4.4 Résultat partiel

11.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 virgules
  • 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 /folders/<folderId>/?orderBy=title:asc,id:desc&slice=100&offset=20

11.4.4.2 Informations retournées

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

• GET /folders/<folderId>/documents/?fields=document.properties
• GET /folders/<folderId>/documents/?fields=document.properties.id,document.properties.title
• GET /folders/<folderId>/documents/?fields=document.properties.id,document.properties.title
• GET /folders/<folderId>/documents/?fields=document.attributes
• GET /folders/<folderId>/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.

11.4.5 Cache

La collection n'a pas de cache.