wcs/help/fr/api-cards.page

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