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 :
-
document.uri
: uri d'accès à la nouvelle ressource -
document.properties
: liste des valeurs des propriétés -
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 |