4.5 Modification d'un document
4.5.1 URL
PUT /api/v1/documents/<id>
Modification de la dernière révision document ayant l'identifiant <documentId>
.
L'extension ".json" peut être ajoutée pour expliciter le format de sortie.
Exemple :
PUT /api/v1/documents/1234.json
Attention : L'identifiant du document peut être son nom logique, son identifiant numérique. L'identifiant numérique peut référencer n'importe quelle révision du document. Dans tous les cas, la modification porte sur la dernière révision du document.
4.5.2 Content
4.5.2.1 Format JSON
Le contenu de la requête doit contenir une donnée JSON avec la liste des attributs modifiés.
{ "document": { "attributes": { "attrid": { "value": "<value>" } } } }
Le type de la requête est application/json
.
Exemple :
{ "document": { "attributes": { "my_title": { "value": "Hello world" } } } }
Note : Toute donnée additionnelle sera ignorée.
4.5.2.2 Format urlEncoded
Le contenu de la requête contient la liste des valeurs d'attributs à enregistrer. Chaque variable (PUT) est le nom de l'attribut (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 document.
4.5.3 Structure de retour
Le retour est une donnée JSON.
4.5.3.1 En cas de réussite :
La partie data
contient 3 champs :
-
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 attributs -
changes
: liste des valeurs modifiées
Exemple :
{"success" : true, "messages" : [], "data" : { "document" : { "uri" : "api\/v1\/documents\/1057.json", "properties" : { "title" : "Hello World", [...] }, "attributes" : { "my_title" : {"value" : "Hello World", "displayValue" : "Hello World"}, [...] } } }, "exceptionMessage" : "" }
La liste des propriétés est documentée dans la documentation de format collection.
4.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 modifier le document | 403 | API0201 |
Tentative de modification échouée | 500 | API0212 |
Impossible de modifier l'attribut | 500 | API0211 |
Le document est une famille | 403 | API0109 |
NB : On ne peut pas modifier les documents de familles.
Exemple :
Cas d'erreur de privilège
{"success" : false, "messages" : [ { "type" : "error", "contentText" : "Update forbidden", "contentHtml" : "", "code" : "API0201", "uri" : "", "data" : null } ], "data" : null, "exceptionMessage" : "Document \"1057\" access deny : Pas de privil\u00e8ge edit pour le document Hello world [1057]" }
4.5.4 Autres URL d'accès
Vous pouvez aussi accéder à cette ressources via :
PUT /api/v1/families/<famName>/documents/<documentId>
Modification de la dernière révision du document de la famille <famName>
ayant
l'identifiant <documentId>
.
La différence entre les collection
families
et documents
est que pour la collection
families/<famName>/documents/
l'identifiant doit être dans la famille indiquée
pour être retourné sinon une erreur 404 (ressource non trouvée) est retournée.