wcs/help/fr/api-get.page

<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>