239 lines
6.0 KiB
Plaintext
239 lines
6.0 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" id="api-schema" 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>Formulaires, profils utilisateur, etc.</desc>
|
||
|
||
</info>
|
||
|
||
<title>Accès aux listes et schémas de données</title>
|
||
|
||
<p>
|
||
w.c.s expose une API permettant aux logiciels tiers de connaître les différents
|
||
formulaires et leurs schémas de données.
|
||
</p>
|
||
|
||
<note><p>Toutes ces URL sont conformes à la spécification de remontée d'information du
|
||
<em>Portail citoyen</em>, acceptent ainsi un paramètre <code>email</code> ou
|
||
<code>NameID</code>, et nécessitent alors un paramètre <code>orig</code>.
|
||
</p></note>
|
||
|
||
|
||
<section id="forms">
|
||
<title>Formulaires</title>
|
||
|
||
<p>
|
||
La liste des formulaires accessibles à un utilisateur est disponible à
|
||
l'URL <code>/api/formdefs/</code>.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/formdefs/</input>
|
||
<output>
|
||
[{"url": "https://www.example.net/inscriptions/newsletter",
|
||
"title": "Newsletter",
|
||
"slug": "newsletter",
|
||
"count": 17,
|
||
"authentication_required": false,
|
||
"redirection": false,
|
||
"description": "",
|
||
"keywords": [],
|
||
"category": "Inscriptions",
|
||
"category_slug": "inscriptions"},
|
||
{"url": "https://www.example.net/inscriptions/piscine",
|
||
"title": "Piscine",
|
||
"slug": "piscine",
|
||
"count": 6,
|
||
"authentication_required": true,
|
||
"redirection": false,
|
||
"description": "La piscine est ouverte du lundi au samedi.",
|
||
"keywords": ["sport"],
|
||
"category": "Inscriptions",
|
||
"category_slug": "inscriptions"}
|
||
]
|
||
</output>
|
||
</screen>
|
||
|
||
<note>
|
||
<p>
|
||
Note de compatibilité : la même information est disponible à la racine du site,
|
||
quand un entête <code>Accept: application/json</code> est transmis, ou à une
|
||
URL <code>/json</code> autrement.
|
||
</p>
|
||
</note>
|
||
|
||
<p>
|
||
La liste des formulaires accessibles à un utilisateur dans le but de faire une
|
||
saisie backoffice est disponible, sous le même format, via l'URL
|
||
<code>/api/formdefs/?backoffice-submission=on</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Il est également possible d'obtenir un nombre permettant de trier les résultats
|
||
par « popularité » en ajoutant un paramètre <code>include-count=on</code>. Les
|
||
différentes entrées disposeront alors d'une clé <code>count</code>.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
|
||
<section id="categories">
|
||
<title>Catégories</title>
|
||
|
||
<p>
|
||
La liste des catégories est disponible à l'URL <code>/api/categories/</code>.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/categories/</input>
|
||
<output>
|
||
{"data":
|
||
[
|
||
{"url": "https://www.example.net/inscriptions/",
|
||
"slug": "inscriptions",
|
||
"title": "Inscriptions",
|
||
"description": "<p>Pour vous et vos enfants...</p>" },
|
||
{"url": "https://www.example.net/etat-civil/",
|
||
"slug": "etat-civil",
|
||
"title": "État civil"}
|
||
]
|
||
}
|
||
</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Il est possible de passer un paramètre <code>full=on</code> dans l'adresse pour
|
||
obtenir pour chacune des catégories la liste des formulaires qu'elle contient,
|
||
dans une clé supplémentaire, <code>forms</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Les formulaires d'une catégorie précise sont disponibles à l'URL
|
||
<code>/api/categories/<var>slug</var>/formdefs/</code>.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/categories/inscriptions/formdefs/</input>
|
||
</screen>
|
||
|
||
<p>
|
||
Comme pour la liste des formulaires en général, on peut ajouter l'argument
|
||
<code>?backoffice-submission=on</code> à cette URL, pour n'obtenir que les
|
||
formulaires de la catégorie accessibles en saisie backoffice.
|
||
</p>
|
||
|
||
|
||
</section>
|
||
|
||
|
||
<section id="roles">
|
||
<title>Rôles</title>
|
||
|
||
<p>
|
||
La liste des rôles est disponible à l'URL <code>/api/roles</code>.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/roles</input>
|
||
<output>
|
||
{"data":
|
||
[
|
||
{"id": 1,
|
||
"text": "Gestionnaires formulaires",
|
||
"slug": "gestionnaires-formulaires"},
|
||
{"id": 2,
|
||
"text": "Usagers privilégiés",
|
||
"slug": "usagers-privilegies"}
|
||
]
|
||
}
|
||
</output>
|
||
</screen>
|
||
|
||
</section>
|
||
|
||
|
||
<section id="data-schema">
|
||
<title>Schéma de données d'un formulaire</title>
|
||
|
||
<p>
|
||
Le schéma de données d'un formulaire est accessible à l'adresse
|
||
<code>/api/formdefs/<em>slug</em>/schema</code>.
|
||
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"name": "Newsletter",
|
||
"only_allow_one": "false",
|
||
"enable_tracking_codes": "true",
|
||
"confirmation": "true",
|
||
"discussion": "false",
|
||
"fields": [
|
||
{
|
||
"label": "Nom",
|
||
"required": true,
|
||
"type": "string",
|
||
"varname": "nom"
|
||
},
|
||
{
|
||
"label": "Pr\u00e9nom",
|
||
"required": false,
|
||
"type": "string",
|
||
"varname": "prenom"
|
||
},
|
||
{
|
||
"label": "Adresse \u00e9lectronique",
|
||
"required": true,
|
||
"type": "email",
|
||
"varname": "email"
|
||
}
|
||
],
|
||
"workflow": {
|
||
"name": "Workflow Newsletter",
|
||
"id": "1",
|
||
"last_modification_time": "2015-12-12T10:20:45",
|
||
"statuses": [
|
||
{
|
||
"id": "1",
|
||
"name": "Nouveau",
|
||
"forced_endpoint": false
|
||
},
|
||
{
|
||
"id": "2",
|
||
"name": "En cours",
|
||
"forced_endpoint": false
|
||
},
|
||
{
|
||
"id": "3",
|
||
"name": "Terminé",
|
||
"forced_endpoint": false
|
||
}
|
||
]
|
||
}
|
||
}
|
||
</code>
|
||
|
||
|
||
<note>
|
||
<p>
|
||
Note de compatibilité : la même information est disponible en ajoutant
|
||
<code>/schema</code> à l'adresse publique du formulaire, par exemple
|
||
<code>http://www.example.net/inscriptions/newsletter<em>/schema</em></code>.
|
||
</p>
|
||
</note>
|
||
|
||
</section>
|
||
|
||
|
||
</page>
|