Manuel de référence

# Smart Structure

Cette collection décrit les Smart Structures de Anakeen Platform.

# URL

L'URL d'accès est: /api/v2/smart-structures

# Méthodes

La collection smart-structures implémente les éléments suivants:

  • Collection: Il n'y a pas d'accès possible directement auprès de la collection smart-structures
Action URL Action effectuée
GET api/v2/smart-structures/ N/A
POST api/v2/smart-structures/ N/A
PUT api/v2/smart-structures/ N/A
DELETE api/v2/smart-structures/ N/A
  • Ressource
Action URL Action effectuée
GET api/v2/smart-structures/<family> Retourne les propriétés de la Smart Structure family
POST api/v2/smart-structures/<family> N/A
PUT api/v2/smart-structures/<family> N/A
DELETE api/v2/smart-structures/<family> N/A
  • Sous-ressource Smart Element:
Action URL Action effectuée
GET api/v2/smart-structures/<family>/smart-elements/ Liste des Smart Elements de la Smart Structure family
POST api/v2/smart-structures/<family>/smart-elements/ Crée un Smart Element de la Smart Structure family
PUT api/v2/smart-structures/<family>/smart-elements/ N/A
DELETE api/v2/smart-structures/<family>/smart-elements/ N/A
GET api/v2/smart-structures/<family>/smart-elements/<docid> Retourne le Smart Elements docid
POST api/v2/smart-structures/<family>/smart-elements/<docid> N/A
PUT api/v2/smart-structures/<family>/smart-elements/<docid> Met à jour le Smart Element docid
DELETE api/v2/smart-structures/<family>/smart-elements/<docid> Supprime le Smart Element docid

# Propriété d'une Smart Structure

# URL

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

Récupération de la ressource décrivant la Smart Structure family.

Exemple: GET /api/v2/smart-structures/DEVBILL

N.B.

Le nom de la Smart Structure est insensible à la casse.

# 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,
  • document.properties: liste des valeurs des propriétés.

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": []
}

# En cas d'échec

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

Raison Status HTTP Code d'erreur
Accès à la Smart Structure refusé 403 Forbidden ROUTES0101
Smart Structure supprimé 404 Document deleted ROUTES0102
Smart Structure non trouvé 404 Document not found ROUTES0105

# Résultat partiel

La ressource peut être retournée avec plus ou moins d'informations.

  • GET /api/v2/smart-structures/1234.json?fields=document.properties,
  • GET /api/v2/smart-structures/1234.json?fields=document.properties.id,document.properties.title,document.attributes,
  • GET /api/v2/smart-structures/1234.json?fields=document.properties.id,document.properties.title,document.attributes.my_exemple,
  • GET /api/v2/smart-structures/1234.json?fields=document.properties.id,document.properties.title,document.attributes,family.structure.

Par défaut: fields=document.properties

Fields Signification Remarques
document.properties Récupère les propriétés données par défaut "id", "title", "icon", "initid", "name", "revision"
document.properties.<prop> Récupère la propriété indiquée
family.structure Récupère la structure de la Smart Structure

# Consultation des Smart Elements de la Smart Structure

# URL

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

Récupération de la liste des Smart Elements de la Smart Structure family présents sur la plateforme.

Exemple: GET /api/v2/smart-structures/DEVBILL/smart-elements/.

# 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 orderBy),
  • uri: URI d'accès de 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 entrées suivantes:

  • properties: liste des propriétés du Smart Element,
  • attributes: liste des Smart Fields du Smart Element (facultatif),
  • 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-structures/DEVBILL/smart-elements/",
    "documents": [
      {
        "properties": {
          "id": 98109,
          "title": "Bill 0001 ACKERER Kathleen",
          "initid": 98109,
          "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
          "name": null,
          "revision": 0,
          "status": "alive"
        },
        "uri": "/api/v2/smart-elements/98109.json"
      },
      {
        "properties": {
          "id": 98110,
          "title": "Bill 0002 ACKERER Kathleen",
          "initid": 98110,
          "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
          "name": null,
          "revision": 0,
          "status": "alive"
        },
        "uri": "/api/v2/smart-elements/98110.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
Sens de l'orderBy inconnu 400 CRUD0501
Smart Field ou propriété d'orderBy invalide 400 CRUD0502

# Résultat partiel

# Pagination et tri

La liste des Smart Elements peut être paginée et ordonnée.

Les mots 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 :
    • il indique le nombre maximum de documents à retourner, sa valeur est un entier ou le mot clef all,
    • valeur par défaut: 10.
  • offset :
    • indique le nombre d'éléments à exclure avant de retourner la collection.
    • valeur par défaut : 0

N.B.

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

Exemple :

GET /api/v2/smart-structures/<family>/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-structures/<family>/smart-elements/?fields=document.properties,
  • GET /api/v2/smart-structures/<family>/smart-elements/?fields=document.properties.id,document.properties.title.

Par défaut : fields=document.properties

Fields Signification Remarques
document.properties Récupère les propriétés données par défaut "id", "title", "icon", "initid", "name", "revision"
document.properties.all Récupère toutes les propriétés
document.properties.<prop> Récupère la propriété indiquée
document.attributes Ajoute tous les Smart Fields
document.attributes.my_smartField Ajoute le Smart Field my_smartField Si le Smart Field n'existe pas dans un des Smart Elements, il est retourné vide

# Cache

La collection n'a pas de cache.

# Création d'un Smart Element

# URL

POST /api/v2/smart-structures/<family>/smart-elements/

Création d'un Smart Element de la Smart Structure family.

Exemple: POST /api/v2/smart-structures/DEVBILL/smart-elements/

N.B.

Le nom de la Smart Structure est insensible à la casse.

# Contenu

# Format JSON

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

{
    "document": {
      "attributes" : {
          "<attrName>" : {
            "value" : <newValue>
          }
      }
    }
}

Le type de la requête est application/json.

Exemple:

{
  "document": {
    "attributes": {
      "ba_title": { "value": "Hello world" },
      "ba_desc": { "value": "Nice Day" }
    }
  }
}

Note

Toute donnée additionnelle sera ignorée.

Cette forme ne permet pas d'enregistrer directement des fichiers dans le Smart Element.
Pour enregistrer le fichier, il sera nécessaire de passer par la ressource file qui retournera un identifiant valide qui pourra être utilisé comme valeur de Smart Field de type fichier.

# Format urlEncoded

Le contenu de la requête contient la liste des valeurs de Smart Fields à enregistrer. Chaque variable (POST) est le nom du Smart Field (casse insensible).

Le type de la requête est application/x-www-form-urlencoded.

N.B.

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 nouvelle ressource,
  • document.properties: liste des valeurs propriétés,
  • document.attributes: liste des valeurs des Smart Fields.

Exemple:

{
  "success": true,
  "data": {
    "document": {
      "properties": {
        "id": 98406,
        "title": "test de création de devbill",
        "initid": 98406,
        "icon": "/api/v2/images/assets/sizes/24x24c/devbill.png",
        "name": null,
        "revision": 0,
        "state": {
          "reference": "wfam_bill_e1",
          "color": "#00CE01",
          "activity": "",
          "stateLabel": "Initial",
          "displayValue": "Initial"
        },
        "status": "alive"
      },
      "attributes": {
        "bill_title": {
          "value": "test de création de devbill",
          "displayValue": "test de création de devbill"
        },
        "bill_content": {
          "value": null,
          "displayValue": null
        },
        [...]
      },
      "uri": "/api/v2/smart-elements/98406.json"
    }
  },
  "messages": []
}

# En cas d'échec

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

Raison Status HTTP Code d'erreur
Smart Structure non trouvée 404 CRUD0200
Tentative de modification d'un Smart Field inconnu 403 ROUTES0106
Tentative de modification d'un Smart Field sans valeur 403 ROUTES0108
Impossible de modifier le Smart Element 500 ROUTES0107
Erreur lors de la création 500 ROUTES0109

← Smart Element →