171 lines
4.6 KiB
Plaintext
171 lines
4.6 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" id="api-fill" xml:lang="fr">
|
||
|
||
<info>
|
||
<link type="guide" xref="index#api" />
|
||
<revision docversion="0.1" date="2013-01-04" status="draft"/>
|
||
<credit type="author">
|
||
<name>Frédéric Péters</name>
|
||
<email>fpeters@entrouvert.com</email>
|
||
</credit>
|
||
<desc>Transmission de données</desc>
|
||
|
||
</info>
|
||
|
||
<title>Complétion et modification d'un formulaire</title>
|
||
|
||
<p>
|
||
w.c.s expose une API autorisant les logiciels tiers à transmettre des données
|
||
structurées permettant la complétion d'un formulaire ou la modification d'un
|
||
formulaire existant.
|
||
</p>
|
||
|
||
<section id="create">
|
||
<title>Complétion d'un formulaire</title>
|
||
|
||
<p>
|
||
La complétion d'un formulaire se fait par une requête <code>POST</code> à
|
||
l'adresse <code>/api/formdefs/<var>slug</var>/submit</code>, le contenu de
|
||
la requête doit être un dictionnaire contenant obligatoirement un attribut
|
||
<code>data</code> et optionnellement un attribut <code>meta</code> et un
|
||
attribut <code>context</code>.
|
||
</p>
|
||
|
||
<p>
|
||
L'attribut <code>data</code> est obligatoire et contient un dictionnaire
|
||
dont les clés sont les identifiants des champs du formulaire (ou leur
|
||
nom de variable) et les valeurs le contenu de ces champs.
|
||
</p>
|
||
|
||
<list>
|
||
<item>
|
||
<p>
|
||
Les champs de type simple tels que « Texte », « Texte long » ou
|
||
« Courriel » sont des chaînes de caractères.
|
||
</p>
|
||
</item>
|
||
|
||
<item>
|
||
<p>
|
||
Les champs de type « Date » sont des chaînes de caractères au format
|
||
ISO-8601, i.e. <code>YYYY-MM-DD</code>.
|
||
</p>
|
||
</item>
|
||
|
||
<item>
|
||
<p>
|
||
Les champs de type « Fichier » sont des dictionnaires contenant les clés
|
||
<code>filename</code> pour le nom de fichier et <code>content</code> pour le
|
||
contenu de celui-ci, encodé en base64.
|
||
</p>
|
||
</item>
|
||
|
||
<item>
|
||
<p>
|
||
Les champs de type « Carte » sont des dictionnaires contenant les clés
|
||
<code>lat</code> pour la latitute en nombre décimal et <code>lon</code>
|
||
pour la longitude en nombre décimal.
|
||
</p>
|
||
</item>
|
||
</list>
|
||
|
||
<p>
|
||
L'attribut <code>meta</code> est optionnel et contient une série de
|
||
paramètres supplémentaires concernant le formulaire.
|
||
</p>
|
||
|
||
<table shade="rows">
|
||
<title>Métadonnées</title>
|
||
<tr>
|
||
<td><p><code>draft</code></p></td>
|
||
<td><p><code>true</code> pour enregistrer le formulaire comme étant un
|
||
brouillon.</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td><p><code>backoffice-submission</code></p></td>
|
||
<td><p><code>true</code> pour enregistrer le formulaire comme étant
|
||
saisi depuis le backoffice.</p></td>
|
||
</tr>
|
||
</table>
|
||
|
||
<p>
|
||
L'attribut <code>context</code> est également optionnel et contient une
|
||
série de renseignements supplémentaires sur le contexte de l'envoi du
|
||
formulaire. Les attributs reconnus sont <code>channel</code>,
|
||
<code>thumbnail_url</code>, <code>user_id</code> et <code>comments</code>.
|
||
</p>
|
||
|
||
<p>
|
||
L'exemple suivant complète un formulaire d'inscription à une newsletter, qui
|
||
demanderait trois champs : prénom, nom et adresse électronique, ce dernier
|
||
champ ayant le nom de variable <code>email</code>.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Content-type: application/json" \
|
||
-H "Accept: application/json" \
|
||
-d@donnees.json \
|
||
https://www.example.net/api/formdefs/newsletter/submit</input>
|
||
<output>{"err": 0, "data": {"id": "1"}}</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Le fichier de données utilisé (<file>donnees.json</file>) contient le
|
||
dictionnaire JSON suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"data": {
|
||
"1": "Marc",
|
||
"2": "L.",
|
||
"email": "marc@example.net"
|
||
}
|
||
}
|
||
</code>
|
||
|
||
</section>
|
||
|
||
<section id="edit">
|
||
<title>Modification d'un formulaire</title>
|
||
|
||
<p>
|
||
Un formulaire qui peut être modifié (par la présence d'une action de workflow
|
||
de type « Permettre l'édition ») peut également être modifié via un appel à
|
||
l'API, en faisant un <code>POST</code> sur l'adresse du formulaire.
|
||
</p>
|
||
|
||
<p>
|
||
Les données attendues sont similaires à la création d'un nouveau formulaire,
|
||
seuls les champs présents seront pris en compte.
|
||
</p>
|
||
|
||
<p>
|
||
Cet appel :
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Content-type: application/json" \
|
||
-H "Accept: application/json" \
|
||
-d@donnees.json \
|
||
https://www.example.net/api/forms/newsletter/1/</input>
|
||
<output>{"err": 0}</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Avec les données suivantes en entrée, modifiera donc uniquement le champ
|
||
« email ».
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"data": {
|
||
"email": "marc@example.org"
|
||
}
|
||
}
|
||
</code>
|
||
|
||
</section>
|
||
|
||
</page>
|