Contenu - DS - API GraphQL
L'API GraphQL du logiciel Démarches-Simplifiées (DS) permet de :
- consulter :
- les informations d'une démarche,
- la liste et les détails des dossiers d'une démarche,
- les détails d'un dossier spécifique.
- modifier certaines informations d'un dossier : (non testé)
- Envoyer un message à l'usager d'un dossier;
- Changer l'état d'un dossier (accepté, refusé, etc.)
Fonctionnement
- La fonctionnalité est activée par défaut.
- Le jeton d’identification de l’API (token) est à récupérer sur la page de profil (
/profil
) d'un compte utilisateur avec le rôle "administrateur". - L'API est accessible à l'adresse
/api/v2/graphql
(cette URL ne peut pas être consultée dans un navigateur web : code HTTP404 Page Not Found
). - Une fois authentifié en tant qu'administrateur disposant d'un jeton, vous pouvez également accéder à l'éditeur de requêtes en ligne
/graphql
(attention, ne confondez pas cette adresse avec celle de l'endpoint).
URL à utiliser
- Générer votre jeton pour l’API :
/profil
- Éditeur de requêtes :
/graphql
- API (endpoint) :
/api/v2/graphql
nota : cette URL retourne une erreur 404 quand elle est utilisée avec la méthode HTTP GET.
Ressources
- documentation officielle du logiciel Démarches-Simplifiées :
- outils graphiques pour construire les requêtes GraphQL :
- GraphQL Playground
- GraphiQL
- GraphiQL.app : application electron de GraphiQL (pour une mise en œuvre rapide)
- ressources complémentaires :
Projets utilisant l'API GraphQL du logiciel Démarches-Simplifiées
- NodeJs - tchak/ds-graphql-api-example
- plusieurs requêtes type "query" et une requête de "mutation" avec upload de fichier
- voir : index.js
- Rails - Inspecteur Mes-Démarches pour l'instance DS de la Polynésie Française
- voir : app/lib/mes_demarches.rb
require 'graphql/client'
require 'graphql/client/http'
...
host = ENV['GRAPHQL_HOST']
puts "server=#{host}"
graphql_url = host + '/api/v2/graphql'
HTTP = GraphQL::Client::HTTP.new(graphql_url) do
def headers(_context)
{ "Authorization": 'Bearer ' + ENV['GRAPHQL_BEARER'] }
end
end
pp HTTP
...
Schema = GraphQL::Client.load_schema(HTTP) # Fetch latest schema on init, this will make a network request
Client = GraphQL::Client.new(schema: Schema, execute: HTTP)
Mutation = Client.parse <<-'GRAPHQL'
mutation EnvoyerMessage($dossierId: ID!, $instructeurId: ID!, $body: String!, $clientMutationId: String) {
dossierEnvoyerMessage(
input: {
dossierId: $dossierId,
instructeurId: $instructeurId,
body: $body
clientMutationId: $clientMutationId,
}) {
clientMutationId
errors {
message
}
}
}
GRAPHQL
Queries = Client.parse <<-'GRAPHQL'
query Demarche($demarche: Int!) {
demarche(number: $demarche) {
title
groupeInstructeurs {
instructeurs {
id
email
}
}
}
}
GRAPHQL
Exemple d'utilisation avec CURL et JQ
Pré-requis
curl
jq
sudo apt-get install curl
sudo apt-get install jq
Variables
- Le jeton d’identification de l’API (token) est à récupérer sur la page de profil d'un compte utilisateur avec le rôle "administration".
- L'URL du profil est :
https://example.com/profil
API_GRAPHQL_URL="https://example.com/api/v2/graphql"
API_JETON="<YOUR_TOKEN>"
PROCEDURE_ID=2
DOSSIER_ID=4
GET
: page d'erreur 404
Requête HTTP # Requête GET : page d'erreur 404
curl -i ${API_GRAPHQL_URL}
# HTTP/1.1 404 Not Found
# Content-Type: text/html; charset=iso-8859-1
#
# <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
# <html><head>
# <title>404 Not Found</title>
POST
(sans jeton et sans paramètre) : erreur au format JSON
Requête HTTP # Requête POST (sans jeton et sans paramètre) : erreur au format JSON
curl -i -X POST ${API_GRAPHQL_URL}
# HTTP/1.1 200 OK
# Content-Type: application/json; charset=utf-8
#
# {"errors":[{"message":"No query string was present"}]}
Informations concernant une démarche
Requête GraphQL
{
demarche(number: 2) {
state
title
dateCreation
datePublication
description
service {
typeOrganisme
organisme
nom
}
}
}
Jouer la requête avec CURL
# Requête à l'API GraphQL de DS
DS_REQUEST="{ demarche(number: ${PROCEDURE_ID}) { state title dateCreation datePublication description service { typeOrganisme organisme nom } } }"
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token=${API_JETON}" \
--data "{ \"query\": \"${DS_REQUEST}\" }" \
${API_GRAPHQL_URL} | jq
Résultat
{
"data": {
"demarche": {
"state": "publiee",
"title": "Inscription à la Bibliothèque",
"dateCreation": "2020-07-09T00:49:16+02:00",
"datePublication": "2020-07-09T01:12:44+02:00",
"description": "S'inscrire à la bibliothèque de la ville permet...",
"service": {
"typeOrganisme": "collectivite_territoriale",
"organisme": "Mairie de New York",
"nom": "Service Culture"
}
}
}
}
Informations concernant une démarche avec les dossiers
Requête GraphQL
{
demarche(number: 2) {
number
title
dossiers {
nodes {
number
state
usager {
email
}
}
}
}
}
Jouer la requête avec CURL
# Requête à l'API GraphQL de DS
DS_REQUEST="{ demarche(number: ${PROCEDURE_ID}) { title number dossiers { nodes { number state usager { email } } } } } "
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token=${API_JETON}" \
--data "{ \"query\": \"${DS_REQUEST}\" }" \
${API_GRAPHQL_URL} | jq
Résultat
{
"data": {
"demarche": {
"title": "Inscription à la Bibliothèque",
"number": 2,
"dossiers": {
"nodes": [
{
"number": 1,
"state": "en_instruction",
"usager": {
"email": "person1@example.com"
}
},
{
"number": 2,
"state": "en_construction",
"usager": {
"email": "person2@example.com"
}
},
{
"number": 3,
"state": "en_instruction",
"usager": {
"email": "person3@example.com"
}
},
{
"number": 4,
"state": "accepte",
"usager": {
"email": "person4@example.com"
}
}
]
}
}
}
}
Informations concernant un dossier
Requête GraphQL
{
dossier(number: 4) {
number
state
dateDerniereModification
dateTraitement
datePassageEnConstruction
datePassageEnInstruction
usager {
email
}
champs {
label
stringValue
}
instructeurs {
email
}
}
}
Jouer la requête avec CURL
# Requête à l'API GraphQL de DS
DS_REQUEST="{ dossier(number: ${DOSSIER_ID}) { number state dateDerniereModification dateTraitement datePassageEnConstruction datePassageEnInstruction usager { email } champs { label stringValue } instructeurs { email } } }"
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer token=${API_JETON}" \
--data "{ \"query\": \"${DS_REQUEST}\" }" \
${API_GRAPHQL_URL} | jq
Résultat
{
"data": {
"dossier": {
"number": 4,
"state": "accepte",
"dateDerniereModification": "2020-07-19T23:16:51+02:00",
"dateTraitement": "2020-07-19T23:16:44+02:00",
"datePassageEnConstruction": "2020-07-19T23:01:59+02:00",
"datePassageEnInstruction": "2020-07-19T23:16:37+02:00",
"usager": {
"email": "person4@example.com"
},
"champs": [
{
"label": "Nom",
"stringValue": "John Doe"
},
{
"label": "Adresse",
"stringValue": "1246 Rue Velasquez 31300 Toulouse"
}
],
"instructeurs": [
{
"email": "instructeur@example.com"
}
]
}
}
}