301 lines
8.0 KiB
Plaintext
301 lines
8.0 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
||
type="topic" id="api-cards" xml:lang="fr">
|
||
|
||
<info>
|
||
<link type="guide" xref="index#api" />
|
||
<revision docversion="0.1" date="2020-12-06" status="draft"/>
|
||
<credit type="author">
|
||
<name>Frédéric Péters</name>
|
||
<email>fpeters@entrouvert.com</email>
|
||
</credit>
|
||
<desc>Liste de fiches, schémas de données, etc.</desc>
|
||
|
||
</info>
|
||
|
||
<title>Gestion des fiches</title>
|
||
|
||
<p>
|
||
Une application tierce peut créer des fiches, récupérer les données des fiches,
|
||
et peut également obtenir la liste des modèles de fiche et les schémas de
|
||
données associés.
|
||
</p>
|
||
|
||
<section id="create">
|
||
<title>Création d'une fiche</title>
|
||
|
||
<p>
|
||
La création d'une fiche se fait par une requête <code>POST</code> à
|
||
l’adresse <code>/api/cards/<var>slug</var>/submit</code>, le contenu de
|
||
la requête doit être un dictionnaire contenant obligatoirement un attribut
|
||
<code>data</code>.
|
||
</p>
|
||
|
||
<p>
|
||
L’attribut <code>data</code> est obligatoire et contient un dictionnaire
|
||
dont les clés sont les noms de variable (remplacé ici par
|
||
<var>varname</var>) des champs de la fiche 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 « Liste » et « Liste à choix multiples » acceptent
|
||
différentes valeurs selon leur configuration, ceci est décrit dans
|
||
<link xref="api-fill#fill-list"/>.
|
||
</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’exemple suivant crée une fiche « Parking », dont le modèle
|
||
de fiche a comme identifiant « parkings », qui demanderait trois champs :
|
||
adresse (nom de variable <code>adresse</code>), date d'ouverture
|
||
(nom de variable <code>date_ouverture</code>) et nom (nom de variable
|
||
<code>nom</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/cards/parkings/submit<var>?signature…</var></input>
|
||
<output>{"err": 0, "data": {"id": "5"}}</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Le fichier de données utilisé (<file>donnees.json</file>) contient le
|
||
dictionnaire JSON suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"data": {
|
||
"adresse": "rue de l’Opéra",
|
||
"date_ouverture": "2020-11-12",
|
||
"nom": "Parking Opéra-Tolozan"
|
||
}
|
||
}
|
||
</code>
|
||
|
||
</section>
|
||
|
||
<section id="card">
|
||
<title>Récupération des données d’une fiches</title>
|
||
|
||
<p>
|
||
L’exemple suivant récupère les données d’une fiche « Parking », dont le modèle
|
||
de fiche a comme identifiant « parkings ».
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/cards/parkings/5/<var>?signature…</var></input>
|
||
</screen>
|
||
|
||
<p>
|
||
Le contenu ainsi obtenu est le suivant :
|
||
</p>
|
||
|
||
<code mime="application/json">
|
||
{
|
||
"digest" : "Parking Opéra-Tolozan",
|
||
"display_id" : "31-5",
|
||
"display_name" : "Parkings - n°31-5",
|
||
"id" : "5",
|
||
"last_update_time" : "2020-11-24T14:18:16",
|
||
"receipt_time" : "2020-11-06T14:48:07",
|
||
"fields" : {
|
||
"adresse" : "rue de l’Opéra",
|
||
"date_ouverture" : "2020-11-12",
|
||
"nom" : "Parking Opéra-Tolozan"
|
||
},
|
||
"text" : "Parking Opéra-Tolozan",
|
||
"url" : "https://.../backoffice/data/parkings/5/",
|
||
"workflow" : {
|
||
"status" : {
|
||
"id" : "recorded",
|
||
"name" : "Recorded"
|
||
}
|
||
},
|
||
"evolution" : [...],
|
||
"geolocations": {...},
|
||
"roles": {...}
|
||
}
|
||
</code>
|
||
|
||
<p>
|
||
La structure du contenu correspond à celle de l’API de <link xref="#create"/>.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
<section id="listing">
|
||
<title>Liste de fiches</title>
|
||
|
||
<p>
|
||
La liste des fiches d’un modèle donné est destinée à être utilisée par
|
||
un système de synchronisation. Elle ne retourne donc pour chaque fiche 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.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/cards/parkings/list<var>?signature…</var></input>
|
||
<output>{
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"text": "Parking de la place",
|
||
"url": "https://www.example.net/backoffice/data/parkings/1/",
|
||
"last_update_time": "2015-03-26T23:08:45",
|
||
"receipt_time": "2015-03-26T23:08:44",
|
||
"display_id": "12-1",
|
||
"display_name": "Parkings - n°12-1"
|
||
},
|
||
{
|
||
"id": 3,
|
||
"text": "Parking de la rivière",
|
||
"url": "https://www.example.net/backoffice/data/parkings/3/",
|
||
"last_update_time": "2015-03-27T12:11:21",
|
||
"receipt_time": "2015-03-27T12:45:19",
|
||
"display_id": "12-3",
|
||
"display_name": "Parkings - n°12-3"
|
||
}
|
||
]
|
||
}</output>
|
||
</screen>
|
||
|
||
<p>
|
||
Des paramètres peuvent être envoyés dans la requête pour filtrer la liste des
|
||
fiches, ils sont similaires à ceux de l’API de <link
|
||
xref="api-get#listing">récupération d’une liste de formulaires</link>.
|
||
</p>
|
||
|
||
</section>
|
||
|
||
<section id="card-schema">
|
||
<title>Schéma de données</title>
|
||
|
||
<p>
|
||
Une API existe pour récupérer le schéma de données d’un modèle de fiches.
|
||
</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/cards/parkings/@schema<var>?signature…</var></input>
|
||
<output>{
|
||
"always_advertise" : false,
|
||
"appearance_keywords" : null,
|
||
"confirmation" : false,
|
||
"description" : null,
|
||
"detailed_emails" : true,
|
||
"digest_template" : "{{form_var_nom}}",
|
||
"disabled" : false,
|
||
"disabled_redirection" : null,
|
||
"discussion" : false,
|
||
"drafts_lifespan" : null,
|
||
"enable_tracking_codes" : false,
|
||
"expiration_date" : null,
|
||
"fields" : [
|
||
{
|
||
"anonymise" : true,
|
||
"data_source" : {},
|
||
"label" : "Nom",
|
||
"prefill" : {
|
||
"type" : "none"
|
||
},
|
||
"required" : true,
|
||
"type" : "string",
|
||
"validation" : {},
|
||
"varname" : "nom"
|
||
},
|
||
...
|
||
],
|
||
"workflow" : {
|
||
"fields" : [],
|
||
"functions" : {
|
||
"_editor" : "Editor",
|
||
"_viewer" : "Viewer"
|
||
},
|
||
"name" : "Fiche parking",
|
||
"statuses" : [
|
||
{
|
||
"endpoint" : false,
|
||
"forced_endpoint" : false,
|
||
"id" : "recorded",
|
||
"name" : "Recorded",
|
||
"waitpoint" : true
|
||
},
|
||
...
|
||
}
|
||
}</output>
|
||
</screen>
|
||
|
||
</section>
|
||
|
||
<section id="card-models">
|
||
<title>Liste des modèles de fiches</title>
|
||
|
||
<p>Une API permet de récupérer la liste des modèles de fiches.</p>
|
||
|
||
<screen>
|
||
<output style="prompt">$ </output><input>curl -H "Accept: application/json" \
|
||
https://www.example.net/api/cards/@list<var>?signature…</var></input>
|
||
<output>{
|
||
"data" : [
|
||
{
|
||
"custom_views" : [],
|
||
"description" : "",
|
||
"id" : "parkings",
|
||
"keywords" : [],
|
||
"slug" : "parkings",
|
||
"text" : "Parkings",
|
||
"title" : "Parkings",
|
||
"url" : "https://.../backoffice/data/parkings/"
|
||
},
|
||
...
|
||
}
|
||
}</output>
|
||
</screen>
|
||
|
||
</section>
|
||
|
||
</page>
|