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 :

1. document.uri : uri d'accès à la ressource modifiée
2. document.properties : liste des valeurs des propriétés
3. document.attributes : liste des valeurs des attributs
4. 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

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.