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

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>
×