Accès aux listes et schémas de données
w.c.s expose une API permettant aux logiciels tiers de connaître les différents formulaires et leurs schémas de données.
Formulaires
La liste des formulaires accessibles à un utilisateur est disponible à l’URL /api/formdefs/.
GET https://www.example.net/api/formdefs/ [{"url": "https://www.example.net/inscriptions/newsletter", "title": "Newsletter", "slug": "newsletter", "authentication_required": false, "redirection": false, "description": "", "keywords": [], "category": "Inscriptions", "category_slug": "inscriptions"}, {"url": "https://www.example.net/inscriptions/piscine", "title": "Piscine", "slug": "piscine", "authentication_required": true, "redirection": false, "description": "La piscine est ouverte du lundi au samedi.", "keywords": ["sport"], "category": "Inscriptions", "category_slug": "inscriptions"} ]
Note de compatibilité : la même information est disponible à la racine du site, quand un entête Accept: application/json est transmis, ou à une URL /json autrement.
La liste des formulaires accessibles à un utilisateur dans le but de faire une saisie backoffice est disponible, sous le même format, via l’URL /api/formdefs/?backoffice-submission=on.
Il est également possible d’obtenir un nombre permettant de trier les résultats par « popularité » en ajoutant un paramètre include-count=on. Les différentes entrées disposeront alors d’une clé count.
L’information count n’est pas le décompte intégral des demandes, c’est un indice composite donnant davantage de poids aux demandes récentes.
La liste retournée inclura les formulaires désactivés en ajoutant le paramètre include-disabled=on.
Catégories
La liste des catégories est disponible à l’URL /api/categories/.
GET https://www.example.net/api/categories/ {"data": [ {"url": "https://www.example.net/inscriptions/", "slug": "inscriptions", "title": "Inscriptions", "description": "<p>Pour vous et vos enfants...</p>" }, {"url": "https://www.example.net/etat-civil/", "slug": "etat-civil", "title": "État civil"} ] }
Il est possible de passer un paramètre full=on dans l’adresse pour obtenir pour chacune des catégories la liste des formulaires qu’elle contient, dans une clé supplémentaire, forms.
Les formulaires d’une catégorie précise sont disponibles à l’URL /api/categories/slug/formdefs/.
GET https://www.example.net/api/categories/inscriptions/formdefs/Comme pour la liste des formulaires en général, on peut ajouter l’argument ?backoffice-submission=on à cette URL, pour n’obtenir que les formulaires de la catégorie accessibles en saisie backoffice.
Rôles
La liste des rôles est disponible à l’URL /api/roles.
GET https://www.example.net/api/roles {"data": [ {"id": 1, "text": "Gestionnaires formulaires", "slug": "gestionnaires-formulaires"}, {"id": 2, "text": "Usagers privilégiés", "slug": "usagers-privilegies"} ] }
Schéma de données d’un formulaire
Le schéma de données d’un formulaire est accessible à l’adresse /api/formdefs/slug/schema; l’appel doit obligatoirement être signé ou réalisé avec un accès disposant des rôles de gestion sur le formulaire.
{
"name": "Newsletter",
"only_allow_one": false,
"enable_tracking_codes": true,
"tracking_code_verify_fields": ["1"],
"confirmation": true,
"discussion": false,
"fields": [
{
"label": "Nom",
"required": true,
"type": "string",
"varname": "nom"
},
{
"label": "Pr\u00e9nom",
"required": false,
"type": "string",
"varname": "prenom"
},
{
"label": "Adresse \u00e9lectronique",
"required": true,
"type": "email",
"varname": "email"
}
],
"workflow": {
"name": "Workflow Newsletter",
"id": "1",
"last_modification_time": "2015-12-12T10:20:45",
"statuses": [
{
"id": "1",
"name": "Nouveau",
"forced_endpoint": false
},
{
"id": "2",
"name": "En cours",
"forced_endpoint": false
},
{
"id": "3",
"name": "Terminé",
"forced_endpoint": false
}
]
}
}Note de compatibilité : la même information est disponible en ajoutant /schema à l’adresse publique du formulaire, par exemple http://www.example.net/inscriptions/newsletter/schema.