# Smart Element: tags utilisateurs

Cette ressource décrit les tags utilisateur des Smart Elements. Un tag est un mot-clef auquel une valeur est éventuellement associée. Ce tag est associé à un Smart Element pour un utilisateur particulier.

# URL

L'URL d'accès est /api/v2/smart-elements/<docid>/usertags/

# Méthodes

La sous-collection usertags implémente les éléments suivants:

Collection

Action	URL	Action effectuée
GET	/api/v2/smart-elements/<docid>/usertags/	Liste des tags utilisateurs
PUT	/api/v2/smart-elements/<docid>/usertags/	N/A
POST	/api/v2/smart-elements/<docid>/usertags/	N/A
DELETE	/api/v2/smart-elements/<docid>/usertags/	N/A

Ressource

Action	URL	Action effectuée
GET	/api/v2/smart-elements/<docid>/usertags/<tag>	Retourne la définition du tag donné
PUT	/api/v2/smart-elements/<docid>/usertags/<tag>	Modifie un tag existant
POST	/api/v2/smart-elements/<docid>/usertags/<tag>	Ajoute un tag
DELETE	/api/v2/smart-elements/<docid>/usertags/<tag>	Supprime un tag

# Liste des tags utilisateur

# URL

GET /api/v2/smart-elements/<docid>/usertags/

Récupération des tags de l'utilisateur connecté pour le Smart Element docid.

Exemple: GET /api/v2/smart-elements/DEVBILL/usertags/

GET /api/v2/smart-structures/<family>/smart-elements/<docid>/usertags/

Récupération des tags de l'utilisateur connecté pour le Smart Element docid de la Smart Structure family.

# Contenu

Le contenu de la requête est vide.

# Structure de retour

Le retour est une donnée JSON

# En cas de réussite

La partie data contient les champs suivants:

requestParameters: contient un résumé des paramètres de la requête en cours (pagination),
uri: URI d'accès à la collection,
userTags: un tableau de tags utilisateur.
Chaque tag utilisateur est un objet contenant les entrées suivantes:
id: identifiant du tag (les identifiants sont sensibles à la casse),
date: date de pose du tag,
value: valeur de tag,
uri: URI d'accès au tag.

Exemple:

{
  "success": true,
  "data": {
    "uri": "/api/v2/smart-elements/usertags/",
    "requestParameters": {
      "slice": -1,
      "offset": 0
    },
    "userTags": [
      {
        "id": "testTag",
        "date": "2019-08-22 09:41:02",
        "uri": "/api/v2/smart-elements/usertags/DEVBILL",
        "value": true
      }
    ]
  },
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Element non trouvé	404	CRUD0200
Privilège insuffisant pour accéder au Smart Element	403 Forbidden	CRUD0201
Smart Element supprimé	404	CRUD0219

# Pagination et tri

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

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

N.B.

Les paramètres appliqués sont résumés dans le retour de la collection requestParameters.
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). :::

# Récupérer un tag utilisateur

# URL

GET /api/v2/smart-elements/<docid>/usertags/<tag> Récupération du tag tag du Smart Element docid de l'utilisateur connecté.

GET /api/v2/smart-structures/<family>/smart-elements/<docid>/usertags/<tag> Récupération du tag tag du Smart Element docid de la Smart Structure family de l'utilisateur connecté.

Exemple: GET /api/v2/smart-elements/DEVBILL/usertags/testTag

# Contenu

Le contenu de la requête est vide.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data contient les champs suivants:

uri: URI préférentielle d'accès à la ressource,
userTag: Propriété du tag
- id: identifiant du tag (les identifiants sont sensibles à la casse),
- date: date de pose du tag,
- value: valeur du tag. La valeur peut avoir 3 formes:
  - String: donnée chaîne (ex: Hello World),
  - Numérique: donnée numérique (ex: 123.34),
  - Objet: données compatibles JSON ( ex: {"one":12, "two": "Hello"}).

Exemple:

{
  "success": true,
  "data": {
    "uri": "/api/v2/smart-elements/DEVBILL/usertags/testTag",
    "userTag": {
      "id": "testTag",
      "date": "2019-08-22 09:41:02",
      "value": ""
    }
  },
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Element non trouvé	404 Not found	CRUD0200
Privilège d'accès au Smart Element insuffisant	401 Forbidden	CRUD0201
Smart Element supprimé	404 Document deleted	CRUD0219
Tag demandé inexistant	404 Not found	CRUD0223

# Créer un tag utilisateur

# URL

POST /api/v2/smart-elements/<docid>/usertags/<tag>

Création du tag tag pour le Smart Element docid. Le tag est associé à l'utilisateur connecté.

POST /api/v2/smart-structures/<family>/smart-elements/<docid>/usertags/<tag>

Création du tag tag pour le Smart Element docid de la Smart Structure family.

Exemple:

POST /api/v2/smart-elements/DEVBILL/usertags/testTag

Le droit de modifier le Smart Element n'est pas requis pour ajouter un tag. Seul le droit de consulter le Smart Element est requis.

# Contenu

Le contenu contient la valeur du tag. Si elle est vide, la valeur sera égale à la chaîne vide.
Si le contenu est une structure json, la valeur retournée sera une structure.

# Structure de retour

La partie data contient les champs suivants:

uri: URI préférentielle d'accès à la ressource,
userTag: liste des valeurs des propriétés.

Exemple:

{
  "success": true,
  "data": {
    "uri": "/api/v2/smart-elements/DEVBILL/usertags/testTag2",
    "userTag": {
      "id": "testTag2",
      "date": "2019-08-22 10:11:24",
      "value": "Hello"
    }
  },
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Element non trouvé	404 Not found	CRUD0200
Privilège d'accès au Smart Element insuffisant	401 Forbidden	CRUD0201
Smart Element supprimé	404 Document deleted	CRUD0219
Impossible de créer le tag	400	CRUD0224
Tag déjà existant	400	CRUD0225

# Modifier un tag utilisateur

# URL

PUT /api/v2/smart-elements/<docid>/usertags/<tag>

Modification du tag tag du Smart Element docid pour l'utilisateur connecté.

PUT /api/v2/smart-structures/<family>/smart-elements/<docid>/usertags/<tag>

Modification du tag tag du Smart Element docid de la Smart Structure family pour l'utilisateur connecté.

Exemple: PUT /api/v2/smart-elements/DEVBILL/usertags/testTag

N.B.

Si le tag n'existe pas déjà, alors il sera créé.

# Contenu

Le contenu de la requête contient la valeur du tag.
Si il est vide, la valeur est égale à la chaîne vide.
Si le contenu est une structure JSON, la valeur retournée est une structure.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data contient les champs suivants:

uri: URI préférentielle d'accès à la ressource,
userTag: liste des valeurs du tag.

Exemple:

{
  "success": true,
  "data": {
    "uri": "/api/v2/smart-elements/DEVBILL/usertags/testTag2",
    "userTag": {
      "id": "testTag2",
      "date": "2019-08-22 10:17:17",
      "value": {
        "test": "UTAG",
        "value": "Ok"
      }
    }
  },
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Element non trouvé	404 Not found	CRUD0200
Privilège d'accès au Smart Element insuffisant	401 Forbidden	CRUD0201
Smart Element supprimé	404 Document deleted	CRUD0219

# Modifier un tag utilisateur

# URL

DELETE /api/v2/smart-elements/<docid>/usertags/<tag>

Suppression du tag tag du Smart Element docid.

DELETE /api/v2/smart-structures/<family>/smart-elements/<docid>/usertags/<tag>

Suppression du tag tag du Smart Element docid de la Smart Structure family.

Exemple:

DELETE /api/v2/smart-elements/DEVBILL/usertags/testTag2

N.B.

Le droit de modifier le Smart Element n'est pas requis pour supprimer un tag. Seul le droit de consulter le Smart Element est requis.

# Contenu

Le contenu de la requête est vide.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data est vide.

Exemple:

{
  "success": true,
  "data": null,
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Element non trouvé	404 Not found	CRUD0200
Privilège d'accès au Smart Element insuffisant	401 Forbidden	CRUD0201
Smart Element supprimé	404 Document deleted	CRUD0219
Tag demandé inexistant	400	CRUD0223

← Smart Element: révision Smart Element: trash →