LogoLogo
✉️ Contact💬 Forum
Guides de data.gouv.fr
Guides de data.gouv.fr
  • Bienvenue
  • ❓Foire aux questions
  • Documentation de data.gouv.fr
    • Créer un compte utilisateur et rejoindre une organisation
    • Organisation
      • Créer une organisation
      • Suivre l'activité et modifier son organisation
      • Gérer les membres de son organisation
      • Certifier une organisation
      • Supprimer une organisation
    • Jeux de données
      • Publier un jeu de données
        • Publier une Base Adresse Locale
      • Gérer un jeu de données
      • Explorer un jeu de donnée
      • Télécharger le catalogue de données de data.gouv.fr
      • Accéder au catalogue via SPARQL
    • API
      • Publier une API
      • Gérer une API
      • Outils pour les administrations
        • Doctrine des API
        • Accompagnement humain
        • Datapass : Outil d'habilitations
        • Bouquets API Entreprise et API Particulier
    • Réutilisations
      • Publier une réutilisation
      • Gérer une réutilisation
    • Statistiques
    • Ressource communautaire
    • Moissonnage
      • Comprendre les limites du moissonnage
      • Les différents types de moissonneurs
      • Mettre en place un moissonneur
      • Analyser le rapport de moissonnage
      • Moissonnage des plateformes géographiques
    • API de data.gouv.fr
      • Prise en main de l'API
      • Tutoriel d'utilisation
      • Gérer un jeu de données par l'API
      • Référence
        • site
        • datasets
        • reuses
        • discussions
        • organizations
        • spatial
        • users
        • me
        • contacts
        • workers
        • tags
        • topics
        • posts
        • transfer
        • notifications
        • avatars
        • harvest
  • Guides open data
    • Guide juridique
      • Producteurs de données
        • Comprendre la notion d'open data
        • Qui est concerné ?
        • Quelles sont les obligations ?
      • Réutilisateurs de données
        • Respecter les conditions de réutilisation
      • Chronologie de l'open data
    • Guide qualité
      • Evaluer le niveau de qualité d'un jeu de données
      • Préparer un jeu de données de qualité
        • Extraire un jeu de données d'un système d'information
        • Structurer un jeu de données
          • Structurer une Base Adresse Locale
        • Lier des données à un référentiel
      • Documenter des données
        • Bien documenter un jeu de données
        • Diffuser la documentation d'un jeu de données
      • Améliorer la qualité d'un jeu de données en continu
        • Améliorer le score de qualité des métadonnées
        • Connaître et suivre les usages d'un jeu de données
        • Mettre en place une stratégie organisationnelle
      • Maîtriser les schémas de données
        • Comprendre les bénéfices d'utiliser un schéma de données
        • Créer un schéma de données
          • Etape 1 : Phase d'investigation
          • Etape 2 : Phase de concertation
          • Etape 3 : Phase de construction
          • Etape 4 : Phase de promotion et de maintien
          • Focus : Construire un schéma TableSchema
        • Intégrer un schéma de données à schema.data.gouv.fr
        • Produire des données en conformité avec un schéma
        • Indiquer et vérifier qu'une ressource respecte un schéma de données
  • Guides sur l'utilisation des données
    • Introduction à l'open data
      • Comprendre la notion d'open data
      • Comprendre l'écosystème de l'open data
      • Comprendre les conditions d'utilisation des données en open data
      • Découvrir et utiliser data.gouv.fr
    • Guide traitement et analyse de données
      • Trouver des données
      • Prendre connaissance et évaluer la qualité de données
      • Explorer des données
      • Récupérer des données
      • Manipuler des données
        • Ouvrir des données
        • Filtrer des données
        • Nettoyer des données
        • Croiser des données
        • Géocoder des adresses
      • Analyser des données
        • Analyser des données avec le tableur LibreOffice Calc
        • Analyser des données avec Python
        • Analyser des données avec R
      • Visualiser des données
      • Cartographier des données
      • Réaliser des projets utiles et s'inspirer
      • Poser des questions aux producteurs de données
      • Valoriser ses travaux
      • Autres ressources pédagogiques
    • Guide API géographiques
      • Utiliser l'API Adresse
        • Rappel sur les données adresses
        • Géocoder des adresses - théorie
        • Géocoder des adresses - cas pratiques
        • FAQ Adresse
      • Utiliser l'API Découpage administratif
      • Utiliser les tuiles vectorielles
    • Guide données du cadastre
      • Comprendre les données du cadastre et leurs usages
      • Manipuler les données du cadastre
      • Foire aux questions sur le cadastre
    • Guide données météorologiques
    • Guide API "Adresse" de l'IGN
  • Autres ressources utiles
    • Lexique de l'open data
    • Données de la commande publique
      • Publier les données essentielles d’attribution des marchés
      • Déclaration d’un profil d’acheteur
    • Données de forte valeur : métadonnées obligatoires et modalités de rapportage
    • Ressources OpenDataFrance
    • Documentation de transport.data.gouv.fr
    • Les algorithmes publics : pourquoi et comment les expliquer ?
      • Les algorithmes publics : enjeux et obligations
      • Fiche pratique : l'obligation de mention explicite
      • Fiche pratique : l'inventaire des principaux traitements algorithmiques
      • Liste de ressources
    • Codes sources du secteur public : lesquels ouvrir, pourquoi et comment ?
      • Ce document n'est pas...
      • Cadre juridique
    • Catalogage de données - GRIST
    • 📒Guide du participant au Hackathon Météo
      • Ressources du hackathon
        • Données
        • Prise en main des données
        • Outils
        • Programme
        • Informations pratiques
        • Contacts
      • Avant le hackathon
      • Pendant le hackathon : règles et bonnes pratiques
        • Choix du défi
        • Constitution des équipes
        • Sollicitation des mentors
        • Documentation des réalisations
        • Rendu intermédiaire
        • Soumission du projet
        • Evaluation des projets
      • Après le hackathon
        • Evaluation du hackathon
        • Valorisation de votre projet
Propulsé par GitBook
Sur cette page
  • 6 enjeux stratégiques
  • 🔭 Découvrabilité
  • 🔑Accès à la donnée
  • 👷🏻‍♂️ Exploitation des données
  • 👌 Qualité de service
  • 🩺 Curation de la donnée
  • 💶 Modèle économique

Cet article vous a-t-il été utile ?

Modifier sur GitHub
Exporter en PDF
  1. Documentation de data.gouv.fr
  2. API
  3. Outils pour les administrations

Doctrine des API

Ce guide référence la doctrine des API dans les administrations.

PrécédentOutils pour les administrationsSuivantAccompagnement humain

Dernière mise à jour il y a 6 mois

Cet article vous a-t-il été utile ?

Pourquoi une doctrine pour les API ?

Élaboré par la DINUM avec les administrateurs ministériels des données, des algorithmes et des codes sources (AMDAC), ce cadre de recommandations précise le cadre d’action et identifie les bonnes pratiques à poursuivre en matière d’usage et d’exposition d’API par les administrations. L’objectif : favoriser le partage de données entre elles et ainsi faciliter les démarches des usagers.

6 enjeux stratégiques

6 enjeux stratégiques ont été identifiés afin de répondre au mieux aux besoins des utilisateurs, qu’il s’agisse d’administrations ou d’usagers, tout en s’intéressant à la gestion du service proposé.

  • - Catalogue de données et services disponibles

    • Gestion des habilitations d'accès aux API à accès restreint - .

    • Bac à sable d'expérimentation public -

  • 👷🏻‍♂️

    • Utilisation des standards technologiques du moment pour faciliter l'interopérabilité - Reco. 6

    • Stabilité du modèle d'interfaces -

    • Indication du temps de réponse et de la tenue en charge -

    • Transparence sur la disponibilité de l'API -

    • Suivi des consommations des données et services -

  • - gratuité de la donnée et de l'exposition


🔭 Découvrabilité

Cette partie concerne à la fois la visibilité de l'API qui doit être exposée dans les catalogues de données adéquats, ainsi que la découvrabilité de la donnée elle-même qui doit être documentée pour être réellement accessible.

Recommandation 1

En complément de la description, les données et services publiquement accessibles sont visibles sur un catalogue exposé sur Internet, référencé sur les moteurs de recherche usuels et intelligibles (la description des API au sein du catalogue ou de l’API manager propose un contenu destiné aux opérationnels, fonctionnels comme techniques).

Exemples:

Recommandation 2

Pour chaque API exposée, sont disponibles :

  • Une documentation fonctionnelle présentant la sémantique des données, leur qualité ainsi que leur source et leurs propriétés usuelles. Elle explicite également le processus de demande d’accès et l’éligibilité des réutilisateurs. Si un catalogue existe, un lien vers la description de la donnée est proposé ;

  • Une documentation technique présentant les modalités d’interrogation et de récupération de la donnée ;

  • Les conditions générales d’utilisation précisant les conditions contractuelles d’accès à l’API ;

La description d’une API décrit également les périodes de validité de l’interface (cf. recommandation s 7 & 8) et son niveau de service (cf. recommandations 10 & 11).

🔑Accès à la donnée

Recommandation 3

L’accès aux API à accès restreint se fait par demande du réutilisateur (administrations, éditeurs, entreprises…).

Les API peuvent s’appuyer sur un mécanisme d’authentification de l’utilisateur final assurant une gestion des droits au sein de la plateforme qui les fournit. Les dispositifs d’authentification des citoyens, des agents ou des personnes morales conçus par les pouvoirs publics pourront être utilisés, en particulier lorsque le consentement de l’utilisateur est nécessaire pour faire circuler la donnée :

  • Pour les personnes physiques : FranceConnect, ProConnect, EduConnect

Recommandation 4

Si le droit d’accès n’est pas préétabli, le processus de demande se fait de la manière la plus simple possible pour le réutilisateur.

Recommandation 5

A chaque API devrait correspondre une version “bac à sable”, accessible en fonction du caractère des données ouvertes ou en accès restreint, exposant une version fictive des données et présentant les mêmes modalités techniques d’exposition.

Pour les API ouvertes, le bac à sable potentiel est accessible au grand public, sans demande préalable du réutilisateur. Pour les API à accès restreint, le bac à sable contenant des données fictives pourrait être accessible au réutilisateur après demande d’un jeton au fournisseur de données, bien que cette pratique ne soit pas recommandée.

👷🏻‍♂️ Exploitation des données

Recommandation 6

Les données et services sont exposés selon des standards techniques communément partagés et adoptés afin de faciliter l'interopérabilité.

👍 Bonne pratique : L’approche « contract first », par opposition à l’approche « code first », est recommandée dans le développement de nouvelles interfaces car elle permet de les stabiliser et de faire travailler plusieurs équipes en parallèle au sein d’une même architecture.

Recommandation 7

Les données et services sont exposés selon une interface (modalités d’appel et structuration des données échangées) définie pour une période donnée.

Les développements Agile ou nécessitant une évolution prévisible seront rendus identifiables et préciseront une période de validité courte de 1 à 2 mois.

Recommandation 8

Ces périodes de validité de l’interface sont explicitement présentées aux réutilisateurs dans la documentation. Les modifications prévisibles s’accompagneront de l’actualisation préalable des informations descriptives intégrant des liens vers des communications et guides permettant aux réutilisateurs d’anticiper les évolutions.

Les réutilisateurs pourront basculer durant une période définie et communiquée sur la version modifiée de l’interface. Durant ce laps de temps, deux interfaces cohabiteront, la version précédente dépréciée et la nouvelle version.

Le détail de ces informations sera présenté en détail dans les conditions générales d’utilisation de l’API.

Recommandation 9

Toute modification non rétro-compatible pose un versionning en tant que version majeure et une cohabitation de l’ancien et du nouveau modèle pendant une période de recouvrement. Celle-ci doit être communiquée à l’avance en diffusant le nouveau contrat d’interface de l’API. A défaut d’information préalable ou d’accord des réutilisateurs, la période de cohabitation sera comprise entre 6 mois et 1 an.

Si une évolution de la donnée interdit le maintien de l’ensemble des fonctionnalités de l’API (exemple : modification d’un schéma avec abandon de certaines informations), il sera indiqué quelles requêtes ou parties du protocole seront maintenues.

👌 Qualité de service

Recommandation 10

La charge admise par une API est consultable en toute transparence par les réutilisateurs :

1. Dans le cas d’une API authentifiée, la charge est exprimée sous forme de métriques propres à chaque réutilisateur, comme le nombre d’appels sur une période donnée par exemple ;

2. Dans le cas d’une API non authentifiée, la charge tenable est exprimée dans son ensemble, tous réutilisateurs confondus ;

3. Dans le cas d’une infrastructure permettant, via une API, des requêtes complexes, ou servant de nombreuses données, la charge tenable estimée indiquera les critères utilisés et le caractère estimatif de cette évaluation ;

4. Dans le cas d’une API sujette à des fortes évolutions en fonction de la saisonnalité, le temps de réponse maximal sera précisé ainsi que les risques de rupture de service.

Recommandation 11

Les temps de réponse moyens et maximaux sont présentés dans la documentation de l’API. Les temps de réponse mesurés ou estimés sont fournis à titre indicatif et non contractuel. Tout autre démarche relève d’un d’accord entre le fournisseur d’API et les réutilisateurs en fonction de leurs cas d’usages.

Recommandation 12

L’état de l’API représente sa capacité à être appelée dans les conditions réelles par un réutilisateur. Il est rendu accessible aux réutilisateurs et consultable en temps réel sous forme d’une URL, indiquée dans la description de l’API, permettant de tester que l'API se déclare disponible et requetable. En complément, il est souhaitable de permettre de consulter un historique entre 6 mois et une année.

Exemple pour l'API Particulier

Recommandation 13

Les consommations des API sont enregistrées pour être ensuite restituées aux bénéficiaires (réutilisateur, producteur, API managers ou exploitants).

👍 Bonne pratique : les bénéficiaires ont accès à travers un portail à une restitution en temps réel ou ponctuelle de ces statistiques de consommation des données ainsi que celles des autres bénéficiaires.

🩺 Curation de la donnée

Recommandation 14

Les réutilisateurs disposent d’un moyen technique ou organisationnel leur permettant de faire des retours sur la qualité des données vers leur gestionnaire ou via la description des données au sein de leur catalogue d’origine.

Les réutilisateurs disposent également d’un moyen technique ou organisationnel leur permettant de faire des retours sur la qualité des API exposées vers leur fournisseur ou via la description de l’API.

💡 Exemple : Le dispositif Datapass pouvant être utilisé par les API en accès restreint permet de faire un retour sur la qualité des données disponibles via celles-ci.

💶 Modèle économique

Recommandation 15

L’accès à la donnée et aux services doit être égalitaire. Les fournisseurs de données cherchent à adapter les modalités d’accès aux besoins des réutilisateurs.

Recommandation 16

Les données ainsi que les API sont mises à disposition gratuitement, pour les réutilisateurs uniquement, sauf exceptions devant faire l’objet d’une justification par l’administration productrice.

💡 Exemple : Dans le cas où des usages nécessiteraient une qualité de service au-dessus de ce que la multitude d’utilisateurs a couramment besoin, comme par exemple une bande passante élevée pour de la donnée temps-réel volumineuse desservie sur quelques organismes, il sera possible d’organiser un système freemium avec une égalité d’accès à des APIs par défaut et des APIs faisant l’objet de redevances pour les usages les plus exigeants.

La description d’une donnée doit référencer les API qui l’exposent. L’exemple ci-dessous présente les API disponibles pour la , sur la page correspondant à ce jeu de données sur data.gouv.fr :

(anciennement API.gouv.fr) vise à référencer toutes les API publiques de l’État ;

vise à référencer toute la verticale métier des finances publiques.

vise à référencer toutes les API délivrant des données administratives des entreprises et des associations. De même pour, pour les données administratives des particuliers.

Dans le cadre de demandes d’accès prévues par la loi et si le demandeur est éligible, une réponse sera transmise aux réutilisateurs dans un délai recommandé de 15 jours calendaires. Le code des relations entre le public et l’administration prévoit un délai légal maximum de 30 jours pour répondre à une demande .

Ressource utile :

En 2022, le principe d’architecture et d’encodage le plus connu et pratiqué est le standard REST Json pour les API synchrones. Il est utilisé par exemple pour les spécifications du standard OpenAPI () ou les standards "API" de l'OGC (). Concernant les API asynchrones, le principe AsyncAPI est le plus répandu.

La disponibilité de l'API Particulier est accessible à cette page :

👉 Voir le cadre interministériel d’administration de la donnée, publié en septembre 2021
🔭 Découvrabilité
🔑 Accès à la donnée
Reco. 3 & 4
Reco. 5
Exploitation des données
Reco. 7, 8 & 9
👌 Qualité de service
Reco. 10 & 11
Reco. 12
Reco. 13
🩺 Curation de la donnée
💶 Modèle économique
base Sirene des entreprises et de leurs établissements
Data.gouv.fr/dataservices
API Impôt Particulier
API Entreprise
API Particulier
(article R311-13)
🔎 DataPass : Délivrer des habilitations juridiques d'accès aux données de l'État
https://spec.openapis.org/oas/v3.1.0
https://ogcapi.ogc.org
https://status.particulier.api.gouv.fr/