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.

Toutes ces URL sont conformes à la spécification de remontée d'information du Portail citoyen, acceptent ainsi un paramètre email ou NameID, et nécessitent alors un paramètre orig.

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",
  "count": 17,
  "authentication_required": false,
  "redirection": false,
  "description": "",
  "keywords": [],
  "category": "Inscriptions",
  "category_slug": "inscriptions"},
 {"url": "https://www.example.net/inscriptions/piscine",
  "title": "Piscine",
  "slug": "piscine",
  "count": 6,
  "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.

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.

{
    "name": "Newsletter",
    "only_allow_one": "false",
    "enable_tracking_codes": "true",
    "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 20 septembre 2020 19:43 — Éditer