-
Notifications
You must be signed in to change notification settings - Fork 2
Documentation API & Guide d'intégration
Bienvenue dans la documentation de l'API Data.Subvention ! Vous trouverez ici des explications sur le fonctionnement de l'API, vous trouverez également un guide d'intégration de l'API.
En cas de question sur l'API, n'hésitez pas à nous contacter à [email protected].
L'API est en cours de développement et son évolution est assez rapide. En principe nous ne faisons pas de modification bloquante pouvant rendre votre intégration obsolète. Néanmoins, les nouvelles fonctionnalités qui sortent régulièrement peuvent engendrer des effets de bord non désirés. Nous ne pouvons que vous encourager à vous tenir au courant des mises à jour.
L'API est une API HTTP, accessible à l'adresse http://api.datasubvention.beta.gouv.fr/.
Vous pouvez également retrouver le Swagger ICI.
Elle comprend une partie qui est accessible sans authentification qui contient :
- Des routes pour l'inscription, la connexion, etc
- Des routes qui fournissent des données ouvertes (/open-data/xyz)
La seconde partie est accessible uniquement après authentification. Toutes les routes sont accessibles suite à une authentification sauf les routes dites "admin"; qui elles, ne sont accessibles qu'aux administrateurs de la plateforme.
À l'heure actuelle, l'API utilise exclusivement le format JSON pour ses entrées comme pour ses sorties. Plusieurs formats devraient être acceptés dans le futur (pas de date de prévu pour le moment).
Si vous développez votre intégration avec TypeScript, vous pouvez retrouver tous les types de retour ICI.
L'API peut être consommée grâce à deux types de compte, un compte utilisateur ou un compte consommateur.
Il s'agit du compte par défaut sur notre plateforme, grâce à celui-ci, vous avez accès à la plupart des routes. Avec ce type de compte, l'authentification n'est valide que sur une période de deux jours, après quoi il faudra vous reconnecter.
Le compte consommateur a été créé spécialement pour les développeurs souhaitant intégrer les données de notre API dans leurs systèmes. Il donne accès aux mêmes ressources qu'un compte utilisateur, mais permet une authentification qui n'est pas limitée dans le temps.
Ici, nous ne parlerons que de l'utilisation en tant que consommateur de l'API (Les comptes utilisateurs ayant pour but d'êtres attribués à des personnes physiques).
Pour initier la création d'un compte consommateur, vous devez nous contactez par mail à [email protected].
L'accès à nos données étant limité aux agents du gouvernement français, nous validons à la main la création des comptes consommateurs.
Vous recevrez ensuite un mail qui vous permettra d'activer votre compte.
Une fois ce dernier activé, vous pourrez vous connecter à la plateforme web.
Pour se connecter à la plateforme, envoyez une requête POST à /auth/login avec vos identifiants.
curl '$API_LINK/auth/login' -H 'accept: application/json' -H 'Content-Type: application/json' -d '{ "password": "string", "email": "string" }'
La requête de connexion renvoie les données liées au compte utilisateur. Dans ces informations se trouve votre token d'authentification (user.jwt.token). (Voir ici).
Ce token utilisateur n'est valable que deux jours.
Pour l'utiliser, voir la partie 4.
Il vous suffit d'envoyer une requête GET à /consumer/token.
Le token que vous récupérez est votre token unique, vous pouvez l'utiliser pour tous les autres appels à l'API.
Ce token a une durée de vie illimitée.
Pour l'utiliser, voir la partie 4.
Pour authentifier une requête, vous devez passer un token (utilisateur ou consommateur) en utilisant au choix :
- Un attribut token dans la query de votre requête
- Un attribut x-access-token dans les headers de votre requête (cette solution est la plus élégante)
Pour l'exemple, nous allons récupérer les informations sur l'association MOUVEMENT ATD QUART MONDE (RNA: W751003066).
curl --location --request GET '$API_LINK/association/W751003066' --header 'x-access-token: UNIQUE_AUTH_TOKEN'
Vous devriez recevoir une réponse au format :
{
association: // Les données sur l'association
}
Les données retournées via l'API ont un format qui permet d'identifier d'où vient la donnée et sa date de mise à jour.
Une donnée est représentée selon le format :
interface ProviderValue<T=unknown> {
provider: string,
type: string,
last_update: Date,
value: T,
}
Si plusieurs sources peuvent fournir la même donnée, alors le format est un tableau contenant des objets ProviderValue ordonnés.
Pour donner un peu plus de contexte, admettons que vous souhaitiez retrouver l'adresse d'un établissement X. En interne de notre API nous allons demander à plusieurs fournisseurs (autres APIs ou données RAW qui sont stockées en interne) les informations concernant l'établissement X. Chaque fournisseur va nous transmettre ses données. Lorsque tous les fournisseurs nous auront répondu, nous créerons un tableau contenant les données de chaque fournisseur. Pour ordonner ce tableau, nous avons attribué un indice de confiance à chaque fournisseur. La donnée la plus fiable sera donc remontée en premier. Si deux données ont un score de confiance équivalent, elles seront alors ordonnées par date de mise à jour.
Donc pour l'exemple, voici à quoi pourrait ressembler l'attribut adresse retourné par notre API :
adresse : [
{
value: {
numero: 5,
type_voie: "RUE,
voie: "du monde ",
code_postal: 66666,
commune: "Aillieur",
},
provider: "BASE RNA <Via API ASSO>"
last_update: 2022-01-01,
type: "object"
},
{
value: {
voie: "5 rue du monde",
code_postal: 66666,
commune: "Aillieur",
},
provider: "BASE SIREN <Via API ASSO>"
last_update: 2021-01-01,
type: "object"
},
...
]
Puisque notre service dépend d'autres APIs, nous ne pouvons malheureusement pas garantir un temps de réponse précis. Nous avons néanmoins mis en place un système de cache qui permet de limiter (une fois la mise en cache effectuée) la latence de réponse.
Chaque consommateur est limité à 80 requêtes par minutes
Le service est disponible 24H/24H et 7J/7J.