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.