5.4 Consultation d'une révision d'un document
5.4.1 URL
GET /api/v1/documents/<documentId>/revisions/<revisionNumber>
Récupération de la révision <revisionNumber>
de la dernière révision d'un
document ayant l'id <documentId>
.
L'extension ".json" peut être ajoutée pour expliciter le format de sortie.
Exemple :
GET /api/v1/documents/1234/revisions/0.json
L'identifiant du document peut être son nom logique, son identifiant numérique.
5.4.2 Content
Le contenu de la requête est vide.
5.4.3 Structure de retour
Le retour est une donnée JSON.
5.4.3.1 En cas de réussite :
La partie data
contient 3 champs :
-
revision.uri
: uri d'accès à la ressource modifiée -
revision.properties
: liste des valeurs des propriétés -
revision.attributes
: liste des valeurs des attributs
Les attributs en visibilité "I" ne sont pas retournés.
Exemple :
{ "success": true, "messages": [], "data": { "revision": { "properties": { "id": 28203, "title": "Le monde sous-marin", "icon": "api/v1/images/assets/sizes/24x24c/article.gif", "initid": 7120, "name": null, "revision": 17, "state": { "reference": "my_transmited", "color": "#A8E5FF", "activity": null, "stateLabel": "Transmis", "displayValue": "Transmis" } }, "attributes": { "de_reference": { "value": "1", "displayValue": "1" }, "de_version": { "value": "Deuxième", "displayValue": "Deuxième" },... }, "uri": "http://www.example.net/api/v1/documents/7120.json" } } }
5.4.3.2 En cas d'échec
Les raisons d'échecs spécifiques à cette requête sont
Raison | Status HTTP | Error Code |
---|---|---|
Révision ou document non trouvé | 404 | API0220 |
Privilège insuffisant pour accéder au document | 403 | API0201 |
Document supprimé | 404 | API0219 |
Propriété demandée inexistante | 400 | API0202 |
Attribut demandé inexistant | 400 | API0218 |
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" }
5.4.4 Résultat partiel
Le document peut être retourné avec plus ou moins d'information.
- GET /documents/1234/revisions/0.json?fields=document.properties
- GET /documents/1234/revisions/0.json?fields=document.properties.status,document.attributes
- GET /documents/1234/revisions/0.json?fields=document.properties.id,document.properties.title,document.attributes.my_exemple
- GET /documents/1234/revisions/0.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", "id", "initid", "revision", "icon", "name" |
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.
5.4.5 Cache
Dans le cadre du cache, le Etag
est calculé à l'aide des éléments suivants :
- id de la révision,
- 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
.
5.4.6 Autres URL d'accès
Vous pouvez aussi accéder à cette ressources via :
GET /api/v1/families/<famName>/documents/<documentId>/revisions/<revisionNumber>
Récupération de la révision <revisionNumber>
de la dernière révision d'un document de la famille <famName>
ayant
l'identifiant <documentId>
.
La différence entre les collection families
et documents
est que pour
la collection /api/v1/families/<famName>/documents/<documentId>/revisions/<revisionNumber>
l'identifiant doit être dans la famille indiquée pour être retourné sinon une
erreur 404 (ressource non trouvée) est retournée.
La révision d'un document "supprimé" pevent être récupérés via l'url
GET /api/v1/trash/<documentId>/revisions/<revisionNumber>