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 :

1. revision.uri : uri d'accès à la ressource modifiée
2. revision.properties : liste des valeurs des propriétés
3. 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

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

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>