Gestion des fiches
Une application tierce peut créer des fiches, récupérer et modifier 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.
Création d’une fiche
La création d’une fiche se fait par une requête POST à l’adresse /api/cards/slug/submit, le contenu de la requête doit être un dictionnaire contenant obligatoirement un attribut data.
Le slug est l’identifiant non-numérique utilisé dans les URL, il est visible depuis l’écran d’un modèle de fiche, dans la fenêtre de modification du titre.
L’attribut data est obligatoire et contient un dictionnaire dont les clés sont les noms de variable (remplacé ici par varname) des champs de la fiche et les valeurs le contenu de ces champs.
Les champs de type simple tels que « Texte », « Texte long » ou « Courriel » sont des chaînes de caractères.
Les champs de type « Liste » et « Liste à choix multiples » acceptent différentes valeurs selon leur configuration, ceci est décrit dans Transmission des champs « Liste » et « Liste à choix multiple ».
Les champs de type « Date » sont des chaînes de caractères au format ISO-8601, i.e. YYYY-MM-DD.
Les champs de type « Fichier » sont des dictionnaires contenant les clés filename pour le nom de fichier et content pour le contenu de celui-ci, encodé en base64.
Les champs de type « Carte » sont des dictionnaires contenant les clés lat pour la latitute en nombre décimal et lon pour la longitude en nombre décimal.
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 adresse), date d’ouverture (nom de variable date_ouverture) et nom (nom de variable nom).
POST https://www.example.net/api/cards/parkings/submit {"err": 0, "data": {"id": "5"}}
Avec les données suivantes en entrée :
{
"data": {
"adresse": "rue de l’Opéra",
"date_ouverture": "2020-11-12",
"nom": "Parking Opéra-Tolozan"
}
}
Il n’y a aucune vérification du format des données reçues, elles sont enregistrée telles quelles. Les contraintes de validation ou les conditions d’affichage ne sont pas prises en compte.
Création d’un ensemble de fiches par import CSV
Il est possible de créer un ensemble de fiches par import d’un fichier CSV. Cela s’effectue par une requête PUT à l’adresse /api/cards/slug/import-csv. Le contenu de la requête doit être un fichier CSV (text/csv).
Chaque ligne du fichier va provoquer la création d’une nouvelle fiche et lancer le workflow correspondant.
PUT https://www.example.net/api/cards/slug/import-csv {"err": 0}
Le fichier CSV doit suivre le même format que celui utilisé lors d’un import CSV dans l’interface de gestion.
Quand le modèle de fiche définit un identifiant personnalisé pour les fiches, il est possible de définr le comportement à adopter concernant les fiches qui auraient le même identifiant : update-mode=update pour faire la mise à jour, update-mode=skip pour ignorer ces fiches. Le comportement sur les fiches existantes mais absentes du fichier CSV peut également être contrôlé, delete-mode=keep pour les conserver, delete-mode=delete pour les supprimer.
Import CSV asynchrone (recommandé)
En plus de la création des fiches, le workflow va être exécuté pour chacune : sur un fichier CSV important le temps d’exécution de l’import peut dépasser la limite acceptée par le serveur HTTP (souvent 20 ou 30 secondes). Il est donc recommandé d’utiliser l’option asynchrone de l’import CSV.
Pour faire un import asynchrone, ajouter async=on dans les paramètres de l’URL :
PUT https://www.example.net/api/cards/slug/import-csv?async=on { "err": 0, "data": { "job": { "id": "1234", "url": "https://www.example.net/api/jobs/1234/" } } }
Cet appel envoie le fichier CSV, mais il n’est pas aussitôt importé. Une tâche (job) est lancée qui va effectivement faire l’import, et on peut en suivre la progression en appellant son URL indiquée en retour de l’appel PUT.
GET https://www.example.net/api/jobs/1234/ { "err": 0, "data": { "status": "en cours", "label": "Importation des données dans des fiches", "creation_time": 1634910701, "completion_time": null, "completion_status": "23/46 (50%)" } }
Pour suivre la bonne exécution de l’import, il faut appeler cette URL jusqu’à ce que la valeur completion_time soit renseignée. La valeur status permet de savoir alors si l’import s'est correctement déroulé.
Récupération des données d’une fiche
L’exemple suivant récupère les données d’une fiche « Parking », dont le modèle de fiche a comme identifiant « parkings ».
GET https://www.example.net/api/cards/parkings/5/Le contenu ainsi obtenu est le suivant :
{
"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",
"endpoint": false
}
},
"evolution" : [...],
"geolocations": {...},
"roles": {...}
}La structure du contenu correspond à celle de l’API de Création d’une fiche.
Modification des données d’une fiche
Sur le même modèle que les formulaires une fiche qui peut être modifiée (par la présence d’une action de workflow de type « Édition ») peut également être modifiée via un appel à l’API.
Les données attendues sont similaires à la création d’une nouvelle fiche (Création d’une fiche), seuls les champs présents seront pris en compte.
POST https://www.example.net/api/cards/parkings/5/Liste de fiches
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.
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.
GET https://www.example.net/api/cards/parkings/list { "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": 2, "text": "Parking des nénuphars", "url": "https://www.example.net/backoffice/data/parkings/2/", "last_update_time": "2015-03-27T09:03:12", "receipt_time": "2015-03-27T09:03:12", "display_id": "12-2", "display_name": "Parkings - n°12-2" }, { "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" } ] }
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 récupération d’une liste de formulaires. Les autres paramètres de cette API sont également exploitables, pour inclure l’ensemble des données (full=on) ou anonymiser celles-ci (anonymise).
Il est également possible de récupérer une liste filtrée correspondant à une vue personnalisée, en ajoutant l’identifiant de celle-ci à l’adresse, ex :
GET https://www.example.net/api/cards/parkings/list/vue-personnalisee { "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" } ] }
Schéma de données
Une API existe pour récupérer le schéma de données d’un modèle de fiches.
GET https://www.example.net/api/cards/parkings/@schema { "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, "drafts_max_per_user" : 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 }, ... } }
Liste des modèles de fiches
Une API permet de récupérer la liste des modèles de fiches.
GET https://www.example.net/api/cards/@list { "data" : [ { "custom_views" : [], "description" : "", "id" : "parkings", "keywords" : [], "slug" : "parkings", "text" : "Parkings", "title" : "Parkings", "url" : "https://.../backoffice/data/parkings/" }, ... } }