9.3 Liste des tags utilisateur

9.3.1 URL

GET /api/v1/documents/<documentId>/usertags/

Récupération des tags de l'utilisateur connecté pour le document documentId.

Exemple :

GET /api/v1/documents/my_document/usertags/

9.3.2 Content

Le contenu de la requête est vide.

9.3.3 Structure de retour

Le retour est une donnée JSON.

9.3.3.1 En cas de réussite :

La partie data contient :

1. requestParameters : contient un résumé des paramètres de la requête en cours (pagination),
2. uri : URI d'accès de la collection,
3. userTags : un tableau de tags utilisateur

Chaque tag utilisateur est un objet contenant les entrées suivantes :

1. id : identifiant du tag (les identifiants sont sensibles à la casse),
2. date : date de pose du tag,
3. value : valeur du tag,
4. uri : URI d'accès au tag.

Exemple :

{
    "success": true,
    "messages": [],
    "data": {
        "uri": "http://www.example.net/api/v1/documents/34757/usertags/",
        "requestParameters": {
            "slice": -1,
            "offset": 0
        },
        "userTags": [
            {
                "id": "lasttab",
                "date": "2015-01-07 17:40:43",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/lasttab",
                "value": "tst_t_tab_relations"
            },
            {
                "id": "VIEWED",
                "date": "2015-01-07 16:09:13",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/VIEWED",
                "value": ""
            },
            {
                "id": "my_special",
                "date": "2014-12-24 09:21:41",
                "uri": "http://www.example.net/api/v1/documents/34757/usertags/solo",
                "value": {
                    "a": 1
                }
            }
        ]
    }
}

9.3.3.2 En cas d'échec

Les raisons d'échecs spécifiques à cette requête sont

Exemple :

Cas d'erreur de privilège

{"success" :             false,
    "messages" :         [
        {
            "type" :        "error",
            "contentText" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]",
            "contentHtml" : "",
            "code" :        "API0201",
            "uri" :         "",
            "data" :        null
        }
    ],
    "data" :             null,
    "exceptionMessage" : "Document \"1051\" access deny : Pas de privil\u00e8ge view pour le document famille [1051]"
}

9.3.4 Pagination et tri

La liste des tags utilisateur est paginée et ordonnée.

Les mots clefs GET sont les suivants :

• slice :
  • il indique le nombre maximum de tag à retourner, sa valeur est un entier. Si sa valeur est inférieur ou égale à 0, toutes les valeurs sont retournés,
  • sa valeur par défaut '-1',
• offset :
  • indique de passer ce nombre de tags avant de renvoyer les tags restants.
  • valeur par défaut : 0

Les paramètres appliqués sont résumés dans le retour de la collection requestParameter.

Le tri des tags utilisé est basé sur la date de modification. Il est donné dans l'ordre descendant (du plus récent au plus ancien).

Exemple :

• GET /api/v1/documents/my_document/usertags/?slice=10&offset=20