api.gouv.fr catalogue les API produites par les administrations centrales, les collectivités territoriales, les établissements publics… Chaque API est associée à une courte description fonctionnelle, une documentation technique, les modalités d'accès, d'éventuelles ressources supplémentaires et surtout des liens vers les services qui l'utilisent.
api.gouv.fr s'adresse avant tout aux créateurs de services, les consommateurs d'API. Pour cela, nous facilitons la découverte, la compréhension et l'accès aux API et à leurs producteurs.
Les fournisseurs, de leur côté, ont avec ce catalogue un moyen simple de faire connaître leurs API.
Veuillez prendre attache avec l'équipe en complétant le formulaire suivant : 👉 Ajoutez votre API !
2- Créer la page de son API (exemple)
Pour ajouter votre API ou commenter un fichier dans ce dépôt, vous devez au préalable avoir un compte Github.
- Se rendre dans le dossier _data/api.
- Créer le fichier de votre API
api-nom-de-la-nouvelle-api.md. - Utiliser les templates à disposition, commentés avec une explication pour chacun des champs. Les champs indispensables sont indiqués par l'icône épingle (📍) dans le commentaire.
-
Pour les API en open data, appuyez-vous sur le template
template.api-opendata.md.example. -
Pour les API avec accès restreint, appuyez-vous sur le template
template.api-fermees.md.example.
Pour plus de facililité, copier/coller tout le contenu du template dans votre fichier. Dans le cas où vous n'avez pas toutes les informations permettant de compléter les champs, vous pouvez supprimer le champ ou le commenter en ajoutant un # en début de ligne.
Pour que votre fiche API fonctionne, il est impératif qu'elle soit rattachée au nom d'un fournisseur référencé dans le dossier api_gouv/_data/producteurs. 🔎 Ajouter un fournisseur de données
Pour ajouter votre swagger dans API.gouv, il vous faut mettre le lien URL vers le fichier openAPI.
- Si vous avez une URL publique permettant d'accéder au fichier OpenAPI, c'est ce lien que vous devez indiquer.
- Si votre swagger n'est pas disponible par une URL publique, nous pouvons héberger votre swagger pour le rendre disponible. Veuillez nous contacter.
Pour ajouter un lien vers la documentation technique, veuillez utiliser le champ doc_tech_external:.
Votre API est en accès restreint ? Deux champs sont à disposition pour renvoyer les usagers vers la demande d'habilitation :
account_link:vous permet d'ajouter l'URL de votre page de connexion (si il s'agit d'une demande de création de compte) ou de votre procédure d'habilitation.datapass_link:permet d'ajouter le lien vers le formulaire d'habilitation DataPass, produit opéré par la DINUM et permettant l'instruction de demandes d'accès à des données.
Si votre API est uniquement accessible à un type de public, le champ access_page vous permet de créer un composant entonnoir pour vérifier si l'usager est éligible. Vous pouvez voir un exemple de ce parcours ici. Ce parcours est accessible après avoir cliqué sur le bouton "Faire une demande d'habilitation" sur la page de l'API.
access_page:
- who: # Chaque "who" crée un bouton de premier niveau. Limitez-en le nombre pour que l'usager s'y retrouve.
- Un particulier ou une entreprise # Label du bouton
is_eligible: -1 # -1 signifie que ce public n'est pas elligible, la mention "Désolé, vous n’êtes pas éligible 🚫" sera affichée quand l'usager clique sur le bouton.
description: |
Seules les administrations sont habilitées à utiliser l'API XX.
<Button href="/rechercher-api">Rechercher une autre API</Button>
# Cette description vient compléter la mention indiquée par le champ is_eligible.
- who:
- Une collectivité ou une administration
is_eligible: 1 # 1 signifie que ce public est éligible, la mention "Vous êtes éligible 👌" sera affichée quand l'usager clique sur le bouton.
description: |
Conformément aux dispositions XXXX, seul le public XXX est habilité à pouvoir utiliser cette API.
Pour obtenir un agrément, vous devrez **justifier de XXXX**, et vous engager à XXXX.
Vous aurez besoin des informations suivantes pour compléter votre demande d'habilitation :
- Info 1
- Info 2
- Document 1
<Button href="https://datapass.api.gouv.fr/api">Remplir une demande</Button>
- who:
- Un éditeur de logiciel
is_eligible: -1
description: |
Si vous êtes **éditeur de logiciels, c'est à votre collectivité ou administration de faire sa demande d'habilitation.**
<Button href="/rechercher-api">Rechercher une autre API</Button>
Vous pouvez ajouter tout le contenu markdown que vous souhaitez dans le champ description: |. Biensûr, rester le plus concis possible est préférable pour que l'usager se repère. Voici quelques options que vous pouvez utiliser facilement :
Option 1 :
Ajouter un bouton pour proposer de chercher une nouvelle API, en écrivant : <Button href="/rechercher-api">Rechercher une autre API</Button>
Option 2 :
Spécialement pour les API utilisant Datapass comme formulaire d'habilitation, vous pouvez utiliser le composant <NextSteps /> pour ajouter un paragraphe décrivant la liste des documents et informations qui seront demandés.
Il vous suffit de l'ajouter sur une ligne seule à l'intérieur du champ description: |, un exemple est visible dans la forme standard du composant ci-dessus.
Que va ajouter ce composant ?
Ajouter ce composant, revient à ajouter le code suivant : ```Pour remplir votre demande, vous aurez besoin :
- de votre numéro SIRET
- du cadre juridique
- {service_description}
- des coordonnées de l'équipe
- des coordonnées de votre délégué à la protection des données et responsable de traitement {is_editeur && de l’entité pour laquelle vous opérez}
Autres options : Vous voulez aller plus loin ? Créer plus de niveaux d'information ? Les API Particulier et API Entreprise sont un bon exemple dont vous pouvez vous inspirer.
Leur composant entonnoir, également configuré à la base dans le fichier principal, appelle d'autres composants disponibles dans le dossier api_gouv/components/questionTree.
Si vous êtes un nouveau fournisseur de données, vous avez besoin de référencer votre organisation dans API.gouv :
- Créer la fiche fournisseur
fournisseur.md, en l'ajoutant dans le dossierapi_gouv/_data/producteurs - Dans ce fichier, copier/coller le template
template.fournisseur.md.exampleou ajouter au minimum :
---
name: Nom complet du fournisseur
acronym: Nom court qui sera affiché en principal
type: Association | Entreprise privée
logo: fichier.png
---
- Ajouter le logo au format .png dans le dossier
api_gouv/public/images/api-logo. Nommer le logo sous le même nom qu'utilisé dans le fichierfournisseur.mdau niveau du champlogo:.
Node.js >= 16
tl;dr: ./bin/install.sh
Cette application utilise Next.js.
- Installer les dépendances
npm i- Variables d’environnement
Afin de configurer le projet correctement, il est conseillé de créer un fichier .env avec les variables d’environnement nécessaires à l’application.
.env permet de persister les variables d’environnement de développement dans un fichier plutôt que de les définir dans le shell, mais les deux fonctionnent. Cela fonctionne avec dotenv et next-runtime-dotenv.
Copier le fichier de configuration
cp .env.sample .env- Lancer le serveur de développement
./bin/local_dev.shPuis visitez http://localhost:3000/
Par défaut, il écoutera sur le port 3000, pour changer, utiliser npm run dev -p 4242.
Cette application utilise Next.js.
- Installer les dépendances
npm i- Générer les bundles de production
npm run build- Lancer le serveur de production
PORT=3000 npm run start- Linter
npm run lint- Tests unitaires
npm run test- Autres tests
// a11y
npm run check-accessibility
//404
npm run check-broken-links
// no link to datapass staging
npm run check-no-datapass-stagingAvant chaque commit est lancé un script qui redimmensionne et compresse les images des pages de guides :
// a11y
npm run create-thumbnailChaque pull request est déployé dans des review app sur Heroku
Le déploiement se fait par Github action
A chaque "merge" sur master :
- Laissez le déploiement se faire automatiquement sur staging via l'action deploy-staging
- Vérifiez vos changements sur staging
- Lancez manuellement le déploiement sur production : sur deploy-production et cliquez sur "Run workflow" -> "Run workflow"
NB: Si plusieurs déploiements sont déclenchés en même temps, seul le premier va jusqu'au bout. Les autres sont automatiquement interrompus.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent