# Smart Element

Cette collection décrit les Smart Elements de Anakeen Platform

# URL

L'url d'accès est: /api/v2/smart-elements

# Méthodes

La collection Smart Element implémente les éléments suivants:

Collection

Action	URL	Action effectuée
GET	api/v2/smart-elements/	Retourne la liste des Smart Elements
POST	api/v2/smart-elements/	N/A
PUT	api/v2/smart-elements/	N/A
DELETE	api/v2/smart-elements/	N/A

Ressource:

Action	URL	Action effectuée
GET	api/v2/smart-elements/<docid>	Retourne le Smart Element `docid`
POST	api/v2/smart-elements/<docid>	N/A
PUT	api/v2/smart-elements/<docid>	Modifie le Smart Element `docid`
DELETE	api/v2/smart-elements/<docid>	Supprime le Smart Element `docid`
GET	/api/v2/smart-elements/<docid>.xml	Retourne les données XML du Smart Element `docid`
POST	/api/v2/smart-elements/<docid>.xml	N/A
PUT	/api/v2/smart-elements/<docid>.xml	N/A
DELETE	/api/v2/smart-elements/<docid>.xml	N/A

# Consultation de la liste des Smart Element

# URL canonique

GET /api/v2/smart-elements/

Récupération de la liste des Smart Elements présents sur Anakeen Platform.

# 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 et ordre),
uri: URI d'accès à la collection,
documents: un tableau de Smart Elements ( sous la même forme que les Smart Elements unitaires); chaque Smart Element est un objet contenant les champs suivants: - properties: liste des propriétés d'un Smart Element,
attributes: liste des Smart Fields du Smart Element, - uri: URI d'accès au Smart Element.

Exemple:

{
  "success": true,
  "data": {
    "requestParameters": {
      "slice": 10,
      "offset": 0,
      "length": 10,
      "orderBy": "title asc, id desc"
    },
    "uri": "/api/v2/smart-elements/",
    "documents": [
      {
        "properties": {
          "id": 97507,
          "title": "Bill",
          "initid": 97507,
          "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
          "name": "DEVBILL",
          "revision": 0,
          "status": "alive"
        },
        "uri": "/api/v2/smart-structures/DEVBILL.json"
      }
    ]
  }
}

N.B.

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Smart Field ou propriété de `slice` invalide	400	ROUTES0139

# Résultat partiel

# Pagination et tri

La liste des Smart Elements est paginée et ordonnée. Les mts clefs GET sont les suivants:

orderBy : <Smart Field|propriété>: <asc:desc>
- indique dans quel sens la collection doit être triée; on peut mettre plusieurs valeurs séparées par des ,,
- valeur par défaut: title:asc,
slice :
- indique le nombre maximum de Smart Elements à retourner; sa valeur est un entier ou le mot clef all,
- sa valeur par défaut est 10,
offset:
- indique de passer ce nombre de Smart Elements avant de renvoyer les Smart Elements restants,
- valeur par défaut: 0.

N.B.

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

Exemple:

GET /api/v2/smart-elements/?orderBy=title:asc,id:desc&slice=100&offset=20.

# Informations retournées

Les Smart Elements peuvent être retournés avec plus ou moins d'informations:

GET /api/v2/smart-elements/?fields=document.properties,
GET /api/v2/smart-elements/?fields=document.properties.id,document.properties.title.
Note

Par défaut: fields=document.properties.

Fields	Signification	Remarques
document.properties	Récupère l'ensemble des propriétés par défaut	"id","title","icon","initid","name"
document.properties.all	Récupère toutes les propriétés
document.properties.<prop>	Récupère la propriété indiquée
document.attributes.my_attribute	Ajoute l'attribut my_attribute	Si l'attribut n'existe pas dans un des Smart Elements, il est retourné vide.
requestParameters.slice	Nombre maximum de Smart Elements demandés
requestParameters.offset	Nombre de premiers Smart Elements à ignorer
requestParameters.orderBy	Tri demandé
requestParameters.length	Nombre de Smart Elements effectivement retournés

# Cache

La collection n'a pas de cache.

# Consultation d'un Smart Element

# URL canonique

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

Récupération de la dernière version du Smart Element ayant l'identifiant docid.
L'extension .json peut être ajoutée pour expliciter le format de sortie.

Exemple: GET /api/v2/smart-elements/DEVBILL ou GET /api/v2/smart-elements/DEVBILL.json.

N.B.

L'identifiant ajouté peut être, soit:

initid, id de révision ou lastid du Smart Element,
name: nom logique du Smart Element.

Dans tous les cas, le Smart Element retourné est le dernier de sa lignée documentaire.

N.B.

Si vous souhaitez accéder à une révision précise du Smart Element, il faut utiliser la collection /api/v2/smart-elements/<docid>/revisions/.

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

Récupération de la dernière révision du Smart Element de la Smart Structure family ayant l'identifiant docid.

N.B.

La différence entre les collections Smart Structure et Smart Element est que pour la collection smart-structures/<family>/smart-elements/ l'identifiant doit être dans la smart Structure indiquée pour être retourné, sinon une erreur 404 (ressource non trouvée) est retournée.

N.B.

Un Smart Element "supprimé" peut être récupéré via l'url trash.

N.B.

Les Smart Elements accédés via les collections smart-structures/<family>/smart-elements et trash possèdent aussi les sous-collections:

history,
revisions.

# 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:

document.uri: URI d'accès à la ressource modifiée,
document.properties: liste des valeurs des propriétés,
document.attributes: liste des valeurs des Smart Fields.

Exemple:

{
  "success": true,
  "data": {
    "document": {
      "properties": {
        "id": 97507,
        "title": "Bill",
        "initid": 97507,
        "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
        "name": "DEVBILL",
        "revision": 0,
        "status": "alive"
      },
      "uri": "/api/v2/smart-structures/DEVBILL.json"
    }
  },
  "messages": []
}

N.B.

Les valeurs retournées correspondent aux valeurs de la vue de consultation par défaut.

N.B.

Les Smart Fields en visibilité I dans la vue de consultation par défaut ne sont pas retournés. Leur existence n'est dévoilée, ni dans les données, ni dans la structure.

# 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 Document not found	ROUTES0100
Accès au Smart Element refusé	403 Forbidden	ROUTES0101
Smart Element supprimé	404 Document deleted	ROUTES0102

# Résultat partiel

Le Smart Element peut être retourné avec plus ou moins d'informations:

GET /api/v2/smart-elements/DEVBILL.json?fields=document.properties,
GET /api/v2/smart-elements/DEVBILL.json?fields=document.properties.id,document.properties.title,document.attributes,
GET /api/v2/smart-elements/DEVBILL.json?fields=document.properties.id,document.properties.title,document.attributes.my_example,
GET /api/v2/smart-elements/DEVBILL.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", "fromname", "id", "postitid", "initid", "locked", "revision", "wid", "cvid", "profid", "fromid", "owner", "domainid"
document.properties.<prop>	Récupère la propriété indiquée
document.attributes	Récupère les valeurs et les valeurs affichable des Smart Fields
document.attributes.<id>	Récupère la valeur d'un Smart Field particulier
family.structure	Récupère la structure de la Smart Structure

# Cache

Dans le cadre du cache, le Etag est calculé à l'aide des éléments suivants:

identifiant du Smart Element,
date de dernière modification,
identifiant de l'utilisateur,
identifiant des droits portés sur le Smart Element (vecteur de droits),
langue sélectionnée.

Dans changelog Tous ces éléments sont concaténés et ensuite le md4 de cette concaténation finTag constitue le Etag. À partir de la version 2021.01

# Autres URL

Il est également possible de consulter le fichier de configuration du Smart Element:

GET /api/v2/smart-elements/<docid>.xml

# Modification d'un Smart Element

# URL

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

Modification de la dernière révision du Smart Element ayant l'identifiant docid.

L'extension .json peut être ajoutée pour expliciter le format de sortie.

Exemple: PUT /api/v2/smart-elements/DEVBILL.json

Attention

L'identifiant du Smart Element peut être son nom logique ou son identifiant numérique. L'identifiant numérique peut référencer n'importe quelle révision du Smart Element.
Dans tous les cas, la modification porte sur la dernière révision du Smart Element.

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

Modification de la dernière révision du Smart Element de la Smart Structure family ayant l'identifiant docid.

N.B.

La différence entre les collections Smart Structure et Smart Element est que pour la collection smart-structures/<family>/smart-elements/ l'identifiant doit être dans la Smart Structure indiquée pour être retourné, sinon, une erreur 404 (ressource non trouvée) est retournée.

# Contenu

# Format JSON

Le contenu de la requête doit contenir une donnée JSON avec la liste des Smart Fields modifiés.

{
  "document": {
    "attributes": {
      "attrid": {
        "value": "<value>"
      }
    }
  }
}

Exemple:

{
  "document": {
    "attributes": {
      "bill_title": {
        "value": "Test Bill 0040"
      }
    }
  }
}

Note

Toute donnée additionnelle sera ignorée.

# Format urlEncoded

Le contenu de la requête contient la liste des valeurs des Smart Fields à enregistrer. Chaque variable (PUT) est le nom du Smart Field (casse insensible).
Le type de la requête est application/x-www-form-urlencoded.

Note

Ce format peut être utilisé directement depuis un formulaire HTML.
Cette forme permet aussi d'enregistrer des fichiers dans le Smart Element.

# Structure de retour

Le retour est une donnée JSON.

# En cas de réussite

La partie data contient les champs suivants:

document.uri: URI d'accès à la ressource modifiée,
document.properties: liste des valeurs des propriétés,
document.attributes: liste des valeurs des Smart Fields.

Exemple:

{
  "success": true,
  "data": {
    "document": {
      "properties": {
        "id": 98148,
        "title": "Test Bill 0040 BIGLIERI Mathys",
        "initid": 98148,
        "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
        "name": null,
        "revision": 0,
        "status": "alive"
      },
      "attributes": {
        "bill_title": {
          "value": "Test Bill 0040",
          "displayValue": "Test Bill 0040"
        },

        "bill_billdate": {
          "value": null,
          "displayValue": null
        },
        "bill_location": {
          "value": "Toulouse",
          "displayValue": "Toulouse"
        }
      },
      "uri": "/api/v2/smart-elements/98148.json"
    },
    "duration": "0.0300"
  },
  "messages": []
}

# En cas d'échec

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

Raison	Status HTTP	Code d'erreur
Privilège insuffisant pour modifier le Smart Element	403 Forbidden	CRUD0201
Impossible de modifier la Smart Structure	403 Forbidden	CRUD0213
Impossible de modifier le Smart Field	500	ROUTES0107
Tentative de modification échouée	500	ROUTES0109

# Suppression d'un Smart Element

# URL

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

Suppression de la lignée de Smart Elements dont un des membres a l'identifiant docid.
L'extension ".json" peut être ajoutée pour expliciter le format de sortie.

Exemple:

DELETE /api/v2/smart-elements/9760.json

La suppression donne l'ordre de mettre le Smart Element dans la poubelle. Dans ce cas, toute la lignée de Smart Elements du Smart Element est mise à la poubelle.
L'identifiant du Smart Element peut être son nom logique, son identifiant numérique ou celui de n'importe laquelle de ses révisions.
La suppression "physique" (réelle suppression de la lignée en base de données) n'est pas possible.

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

Suppression de la lignée de Smart Elements de la Smart Structure family dont un des membres a l'identifiant docid.

N.B.

La différence entre les collections Smart Structure et Smart Element est que pour la collection smart-structures/<family>/smart-elements l'identifiant doit être dans la Smart Structure indiquée pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.

# 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:

document.uri: URI d'accès à la ressource supprimée,
document.properties: liste des valeurs des propriétés du Smart Element supprimé,
document.attributes: liste des valeurs des Smart Fields du Smart Element supprimé.
Les Smart Fields en visibilité I ne sont pas retournés. Leur existence n'est dévoilée, ni dans les données, ni dans la structure.
Un Smart Element mis à la poubelle n'est plus accessible via la ressource Smart Elements mais reste accessible par la ressource trash.

Exemple:

{
  "success": true,
  "data": {
    "document": {
      "properties": {
        "id": 98147,
        "title": "Bill 0039 BIDART Andréa",
        "initid": 98147,
        "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
        "name": null,
        "revision": 0,
        "status": "deleted"
      },
      "attributes": {
        "bill_title": {
          "value": "Bill 0039",
          "displayValue": "Bill 0039"
        }
      }
    }
  }
}

# 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 Document not found	ROUTES0100
Smart Element non supprimé	404 Document not in the trash	ROUTES0112

La suppression d'un Smart Element hérite également des raisons d'échec spécifiques à la consultation d'un Smart Element

← Smart Structure Smart Element: révision →