help: add page on cards API endpoints (#48362)

help/fr/api-cards.page

@@ -0,0 +1,205 @@
+<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>Récupération des données de fiches</title>
+
+<p>
+Une application tierce peut récupérer les données des fiches, peut également
+obtenir la liste des modèles de fiche et les schémas de données associés.
+</p>
+
+<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 d
+<link xref="api-get#pull">récupération des données d'un formulaire</link>.
+</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>
+</screen>
+
+<code mime="application/json">
+[
+    {
+        url: "https://www.example.net/backoffice/data/parkings/1/",
+        last_update_time: "2015-03-26T23:08:45",
+        receipt_time: "2015-03-26T23:08:44",
+        id: 1
+    },
+    {
+        url: "https://www.example.net/backoffice/data/parkings/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 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>