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 :
-
document.uri
: uri d'accès à la ressource modifiée -
document.properties
: liste des valeurs des propriétés -
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
Raison | Status HTTP | Error Code |
---|---|---|
Document non trouvé | 404 | CRUD0200 |
Privilège insuffisant pour accéder au document | 403 | CRUD0201 |
Document supprimé | 404 | CRUD0219 |
Propriété demandée inexistante | 400 | CRUD0202 |
Attribut demandé inexistant | 400 | CRUD0218 |
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
fields | Signification | Remarques |
---|---|---|
document.properties |
Récupère l'ensemble des propriétés "visibles" | "state", "fromname", "id", "postitid", "initid", "locked", "revision", "wid", "cvid", "profid", "fromid", "owner", "domainid" |
document.properties.<prop> |
Récupère la propriété indiquée | |
document.attributes |
Récupère les valeurs et les valeurs affichable des attributs | |
document.attributes.<id> |
Récupère la valeur d'un attribut particulier | |
document.family.structure |
Récupère la structure de la famille |
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
.