12.5 Création d'un document

12.5.1 URL

POST /api/v1/families/<famName>/documents/

Création d'un document de la famille <famName>

Exemple :

POST /api/v1/families/my_cookbook/documents/

Le nom de la famille est insensible à la casse.

12.5.2 Content

12.5.2.1 Format JSON

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

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

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

Exemple :

{
 
    "document": {
      "attributes" : {
          "ba_ttle" : {"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 document.

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 d'attribut de type fichier.

12.5.2.2 Format urlEncoded

Le contenu de la requête contient la liste des valeurs d'attributs à enregistrer. Chaque variable (POST) est le nom de l'attribut (casse insensible).

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

Ce format peut être utilisé directement depuis un formulaire HTML.

Cette forme permet aussi d'enregistrer des fichiers dans le document.

12.5.3 Structure de retour

Le retour est une donnée JSON.

12.5.3.1 En cas de réussite :

La partie data contient un champ document qui inclut 3 champs :

  1. document.uri : uri d'accès à la nouvelle ressource
  2. document.properties : liste des valeurs des propriétés
  3. document.attributes : liste des valeurs des attributs

Exemple :

{
  success :true,
  messages : [],
  data : {
    "document" : {
          "uri" : "api/v1/documents/1256",
          "properties" : { 
             "id" : 1256,
             "title" : "Hello world",
             ....
           }
          "attributes" : { 
            "ba_title" : {
                "value" : "Hello world",
                "displayValue" : "Hello world"
            },
            "ba_cost" : {
                "value" : 234,
                "displayValue" : "234.00 €"
            }
          }
        }
  }
}

La liste des propriétés est documentée dans la documentation de format collection.

12.5.3.2 En cas d'échec

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

Raison Status HTTP Error Code
Privilège insuffisant pour créer le document de cette famille 403 API0204
Tentative de modification d'un attribut inconnu 403 API0205
Tentative de modification d'un attribut en visibilité I 403 API0205
Erreur lors de la création 403 API0205
Famille inconnue 404 API0206
×