<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>. Les
autres paramètres de cette API sont également exploitables, pour inclure
l’ensemble des données (<code>full=on</code>) ou anonymiser celles-ci
(<code>anonymise</code>).
</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>
