Documentation en ligne

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

$ curl -H "Accept: application/json" \
       https://www.example.net/api/formdefs/?signature…

[{"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/.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/categories/?signature…

{"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/.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/categories/inscriptions/formdefs/?signature…

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.

$ curl -H "Accept: application/json" \
       https://www.example.net/api/roles?signature…

{"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.

Dernière mise à jour le 16 mars 2022 13:44 — Éditer