241 lines
6.4 KiB
Plaintext
241 lines
6.4 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" id="api-get" 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>Pull, push, types de données, etc.</desc>
|
||
|
||
</info>
|
||
|
||
<title>Récupération des données d'un formulaire</title>
|
||
|
||
<p>
|
||
Il s'agit ici d'une API permettant à un logiciel tiers de récupérer les données
|
||
associées à un formulaire complété; cet accès peut aussi bien être initié par
|
||
l'application tierce (mode pull) ou par w.c.s., à différents moments du
|
||
traitement d'un formulaire (mode push).
|
||
</p>
|
||
|
||
<section id="pull">
|
||
<title>Mode « Pull »</title>
|
||
|
||
<p>
|
||
L'exemple suivant récupère les données d'un formulaire d'inscription à une
|
||
newsletter.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/forms/newsletter/16/</input>
|
||
</screen>
|
||
|
||
<p>
|
||
Le contenu ainsi obtenu est le suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"id": "newsletter/16",
|
||
"receipt_time": "2013-01-04T13:39:47",
|
||
"last_update_time": "2013-01-04T13:41:21",
|
||
"fields": {
|
||
"email": "marc@example.net",
|
||
"nom": "L.",
|
||
"prenom": "Marc"
|
||
},
|
||
"user": {
|
||
"id": 1,
|
||
"name": "Fred"
|
||
},
|
||
"workflow": {
|
||
"status": {
|
||
"id": "new",
|
||
"name": "New"
|
||
},
|
||
"data": {
|
||
"creation_status": 200,
|
||
"creation_response": {
|
||
"dn": "cn=marc@example.net,ou=people"
|
||
},
|
||
"inscription_status": 200,
|
||
"inscription_response": {
|
||
"liste": "lalettre@example.com"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
</code>
|
||
|
||
<p>
|
||
Seuls les champs ayant un <em>nom de variable</em> sont exportés dans <code>fields</code>.
|
||
</p>
|
||
|
||
<note>
|
||
<p>
|
||
Il est bien sûr nécessaire de disposer des autorisations nécessaires pour
|
||
accéder ainsi aux données d'un formulaire. (cf <link
|
||
xref="api-auth"/> pour les explications sur le sujet)
|
||
</p>
|
||
</note>
|
||
|
||
</section>
|
||
|
||
<section id="push">
|
||
<title>Mode « push »</title>
|
||
|
||
<p>
|
||
Il est également possible pour un workflow d'être configuré pour transmettre
|
||
les données à une URL fournie par une application tierce. Un document JSON
|
||
(tel celui donné plus haut) est alors transmis en utilisant la méthode POST.
|
||
</p>
|
||
|
||
<p>
|
||
En retour, l'application tierce peut fournir un objet JSON qui sera enregistré
|
||
dans les données du workflow du formulaire (voir le dictionnaire "data" dans
|
||
l'exemple ci-dessus).
|
||
</p>
|
||
|
||
</section>
|
||
|
||
|
||
<section id="datatypes">
|
||
<title>Types de données</title>
|
||
|
||
<p>
|
||
Les données d'un formulaire sont placées dans le champs <code>fields</code> de
|
||
la réponse. Les champs de type simple tels que « Texte », « Texte long » ou
|
||
« Courriel » sont vus en tant que chaîne de caractères :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
(...)
|
||
"fields": {
|
||
"email": "marc@example.net",
|
||
"nom": "L.",
|
||
"prenom": "Marc"
|
||
},
|
||
(...)
|
||
</code>
|
||
|
||
<section>
|
||
<title>Représentation d'un champ « Fichier »</title>
|
||
|
||
<p>
|
||
Les champs de type « Fichier » sont exportés selon le schéma suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
(...)
|
||
"fields": {
|
||
"photo": {
|
||
"filename": "exemple.txt",
|
||
"content_type": "text/plain",
|
||
"content": "Q2VjaSBuJ2VzdCBwYXMgdW4gZXhlbXBsZS4="
|
||
}
|
||
},
|
||
(...)
|
||
</code>
|
||
|
||
<p>
|
||
La valeur de <code>content</code> est le contenu du fichier, encodé en base64.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
</section>
|
||
|
||
<section id="listing">
|
||
<title>Liste de formulaires</title>
|
||
|
||
<note style="important"><p>
|
||
Ce webservice n'est pas encore stabilisé, son URL peut encore changer dans les
|
||
futures versions de w.c.s.
|
||
</p></note>
|
||
|
||
<p>
|
||
La liste des demandes pour un formulaire donné est destinée à être utilisée par
|
||
un système de synchronisation. Elle ne retourne donc pour chaque demande que
|
||
son numéro (id), ses dates de création et de dernière mise à jour.
|
||
</p>
|
||
|
||
<p>
|
||
Un système de synchronisation vérifiera depuis cette liste si de nouvelles
|
||
demandes existent, ou si certaines ont été mises à jour, sont obsolètes ou
|
||
effacées, puis effectuera pour chacune les actions nécessaires (pull, push,
|
||
etc.).
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/forms/inscriptions/list</input>
|
||
</screen>
|
||
|
||
<code mime="application/json">
|
||
[
|
||
{
|
||
url: "https://www.example.net/inscriptions/1/",
|
||
last_update_time: "2015-03-26T23:08:45",
|
||
receipt_time: "2015-03-26T23:08:44",
|
||
id: 1
|
||
},
|
||
{
|
||
url: "https://www.example.net/inscriptions/3/",
|
||
last_update_time: "2015-03-27T12:11:21",
|
||
receipt_time: "2015-03-27T12:45:19",
|
||
id: 3
|
||
}
|
||
]
|
||
</code>
|
||
|
||
<p>
|
||
Des paramètres peuvent être envoyés dans la requête pour filtrer le listing
|
||
voulu. Il s'agit des mêmes paramètres que pour l'export en backoffice, sauf
|
||
pour filter qui est fixé à all par défaut. Pour avoir une liste limitée aux
|
||
demandes non terminées (pending) :
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/forms/inscriptions/list?filter=pending</input>
|
||
</screen>
|
||
|
||
<p>
|
||
Il est également possible de filtrer sur le contenu des formulaires, à partir
|
||
des champs associés à un nom de variable et de type « Liste ». Par exemple sur
|
||
un champ « Type » (nom de variable <code>type</code>) dont une des valeurs
|
||
possibles est « gratuit » :
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/forms/inscriptions/list?filter-type=gratuit</input>
|
||
</screen>
|
||
|
||
<p>
|
||
Afin de faciliter certains traitements <em>batch</em>, il est possible de
|
||
demander que l'ensemble des données associées aux formulaires soient
|
||
retourné, plutôt qu'un jeu réduit adapté aux systèmes de synchronisation.
|
||
Pour ce faire, il suffit de passer un paramètre <code>full=on</code> dans
|
||
l'adresse.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/forms/inscriptions/list?full=on</input>
|
||
</screen>
|
||
|
||
<p>
|
||
À noter que pour ne pas alourdir l'export en mode <code>full=on</code>, les
|
||
champs de type « Fichier » ne sont pas exportés.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
|
||
</page>
|