diff --git a/README.md b/README.md index 8b986f57a..7814fb12e 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,135 @@ Les fournisseurs, de leur côté, ont avec ce catalogue un moyen simple de faire Veuillez prendre attache avec l'équipe en complétant le formulaire suivant : [👉 Ajoutez votre API](https://api.gouv.fr/nouvelle-api) ! -### 2- Ajouter son API dans le code +### 2- Créer la page de son API ([exemple](https://api.gouv.fr/les-api/api-particulier)) -**Créer une fiche métier ([exemple](https://api.gouv.fr/les-api/api-particulier)) :** -- Rdv dans le dossier [_data/api](https://github.com/betagouv/api.gouv.fr/tree/master/_data/api). -- Y ajouter un fichier `api-nom-de-la-nouvelle-api.md` +Pour ajouter votre API ou commenter un fichier dans ce dépôt, vous devez au préalable avoir un [compte Github](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F&source=header-home). + +#### Créer la page à partir des templates disponibles + +1. Se rendre dans le dossier [_data/api](https://github.com/betagouv/api.gouv.fr/tree/master/_data/api). +2. Créer le fichier de votre API `api-nom-de-la-nouvelle-api.md`. +3. 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`](https://github.com/betagouv/api.gouv.fr/tree/master/_data/api/template.api-opendata.md.example). + +- **Pour les API avec accès restreint**, appuyez-vous sur le template [`template.api-fermees.md.example`](https://github.com/betagouv/api.gouv.fr/tree/master/_data/api/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. + +#### Champ `producer` + +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](#3--créermodifier-sa-fiche-fournisseur-de-données) + +#### Champ `doc_tech_link` ou comment référencer son swagger + +Pour ajouter votre swagger dans [API.gouv](https://api.gouv.fr/documentation), 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](https://api.gouv.fr/parcours-client?source=contact). + +Pour ajouter un lien vers la documentation technique, veuillez utiliser le champ `doc_tech_external:`. + +#### `account_link:` et `datapass_link:`quelle différence ? + +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. + + +#### Entonoir d'éligibilité avec `access_page:` + +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](https://api.gouv.fr/les-api/api-statut-demandeur-emploi/demande-acces). Ce parcours est accessible après avoir cliqué sur le bouton "Faire une demande d'habilitation" sur la page de l'API. + +##### Forme standard du champ : + +``` +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. + + + # 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 + + + - 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.** + + +``` + +##### Options du champ `description: |` : + +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 : `` + +**Option 2 :** +Spécialement pour les API utilisant Datapass comme formulaire d'habilitation, vous pouvez utiliser le composant [``](https://github.com/betagouv/api.gouv.fr/tree/master/components/richReactMarkdown/index.tsx) 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](#forme-standard-du-champ). + +
+ Que va ajouter ce composant ? + Ajouter ce composant, revient à ajouter le code suivant : + ``` +

+ Pour remplir votre demande, vous aurez besoin : +

+ + ``` +
+ +**Autres options :** Vous voulez aller plus loin ? Créer plus de niveaux d'information ? +Les [API Particulier](https://api.gouv.fr/les-api/api-particulier) et [API Entreprise](https://api.gouv.fr/les-api/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`](https://github.com/betagouv/api.gouv.fr/tree/master/components/questionTree). + + +### 3- Créer/modifier sa fiche fournisseur de données + +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 dossier [`api_gouv/_data/producteurs`](https://github.com/betagouv/api.gouv.fr/tree/master/_data/producteurs) +- Dans ce fichier, copier/coller le template `template.fournisseur.md.example` ou 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 fichier `fournisseur.md` au niveau du champ `logo:`. -**Ajouter un swagger qui apparaîtra [ici](https://api.gouv.fr/documentation) :** -- Dans la fiche métier, complêter le champ `doc_tech_link` avec un lien vers un swagger en json ou yaml qui est hébergé où vous le souhaitez pour être mis à jour le plus souvent possible. -- En ajoutant ce lien dans la fiche métier, votre swagger apparaîtra automatiquement dans API.gouv. ## Comment ça marche ? diff --git a/_data/api/template.api-fermees.md.example b/_data/api/template.api-fermees.md.example new file mode 100644 index 000000000..a1d817cd5 --- /dev/null +++ b/_data/api/template.api-fermees.md.example @@ -0,0 +1,126 @@ +--- +title: API XXX # 📍 Nom commercial de l'API, privilégier un nom court. +tagline: Entités administratives, interrogez l'API ... # 📍 Une phrase pour résumer le service rendu par l'API. Si votre API est uniquement accessible à certaines organisation, spécifiez-le dès maintenant. +producer: identifiant_fournisseur # 📍 Identifiant du fournisseur de la donnée trouvable ou ajoutable dans le dossier `api_gouv/_data/producteurs`, pour en savoir plus consulter le read.me. +contact_link: contact@contact.fr # 📍 Adresse e-mail que les usagers peuvent utiliser pour vous contacter. +partners: # Liste des co-producteurs de l'API + - dinum # Sera cliquable vers une page détaillant le partenaire car fait partie des fournisseurs référencés dans le dossier `api_gouv/_data/producteurs` + - partenaire # Sera listé sans être cliquable. +is_open: -1 # 📍 -1 si l'API est fermée, accessible à un public restreint sous habilitation ; 0 si un compte est nécessaire pour utiliser l'API mais qu'il n'y a pas de conditions pour se créer un compte. +account_link: https://site-api/user/register # URL de la page de demande d'habilitation si l'API nécessite un compte pour être utilisée. ATTENTION : retirer ce champ si vous utilisez le champ ci-dessous "datapass_link". +datapass_link: https://datapass.api.gouv.fr/api-xxx # URL vers le formulaire d'habilitation Datapass (uniquement API en accès restreint). ATTENTION : retirer ce champ si vous utilisez le champ ci-dessus "account_link". +is_france_connected: -1 # 📍 -1 L'API n'est pas FranceConnectée ; 1 L'API est FranceConnectée. +access_page: +# Ce tableau vous permet de créer un entonnoir pour vérifier l'éligibilité de l'usager avant de le mener vers votre formulaire d'habilitation. Pour en savoir plus sur le fonctionnement de ce composant consulter le read.me. + - who: + - Un particulier ou une entreprise + is_eligible: -1 # -1 signifie que ce public n'est pas elligible, la mention "Désolé, vous n’êtes pas éligible 🚫" sera affichée. + description: | + Seules les administrations sont habilitées à utiliser l'API XX. + + + - who: + - Une collectivité ou une administration + is_eligible: 1 # 1 signifie que ce public est éligible, la mention "Vous êtes éligible 👌" sera affichée. + 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 + + + - 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.** + + +rate_limiting_resume: 10 appels / minute / IP # 📍 Volumétrie maximale de votre API. +rate_limiting_description: | + L'API est disponible à hauteur de 10 appels par minute. +# Phrase descriptive de la volumétrie +doc_tech_link: https://swagger/api/open-api.yml # 📍 URL qui donne accès au swagger de votre API, sur la page API.gouv suivante : https://api.gouv.fr/documentation, accessible depuis le bouton "Tester l'API" sur la fiche de l'API. Pour en savoir plus, consulter le read.me. +doc_tech_external: https://doc-tech-de-votre-site.fr # 📍 URL vers la documentation technique de l'API +monitoring_link: https://page-statut-de-lapi # URL de la page de statut de l'API +stats_detail_resume: Les statistiques sont disponibles en temps réel # Résumer en un titre à quoi peut s'attendre l'usager en termes de statistiques de consommation de l'API. Cette phrase suit le titre "Stats:" qui permet de déplier un volet avec les détails ci-dessous (description et lien) : +stats_detail_description: | + Accédez au suivi des consommations de l'API +stats_detail_link: http://page-stats-dusage-de-lapi # URL de la page des statistiques d'usage de l'API +themes: # 📍 Ajouter un ou plusieurs thèmes, qui permettront aux usagers de trouver votre API en filtrant le catalogue par thématique. Pour ajouter un thème ci-dessous, supprimer simplement le # (sans retirer des blancs.) +# - Administration +# - Administration & législation +# - Agriculture +# - Culture +# - Droit & Justice +# - Education +# - Emploi +# - Energie +# - Entreprise +# - Environnement +# - Géographie +# - Particulier +# - Professionnels +# - Santé +# - Sécurité +# - Transport +keywords: # 📍 Ajouter des mots clés qui permettront aux usagers de trouver votre API avec le moteur de recherche. + - associations + - rna +last_update: 11/10/2023 # Date de la dernière mise à jour de la doc +datagouv_uuid: # Si l'API se base sur un jeu de données ouvertes accessibles depuis data.gouv.fr, ajouter l'uuid du jeu de données pour afficher automatiquement un bloc en fin de page référençant le jeu de données. + - 631f4320d215a236920bd4dd +content_intro: | + ### À quoi sert l'API XXX ? + + L'API XXX délivre les informations et documents de référence de XXX, informations issues du répertoire XXX et de la base YYY. +# 📍 Ce champ apparaîtra en haut de la fiche de l'API, sous le titre description. Le texte ci-dessus est un exemple et montre comment ajouter un lien vers l'extérieur. + +--- + + +## Périmètre de l'API + +### Entitées concernés : + +Cette API concerne ✅ **les associations inscrites au répertoire national des associations (RNA) et/ou au répertoire Sirene**. + +Cette API ne concerne pas : +- ❌ les associations du régime Alsace-Moselle ; +- ❌ les associations XX. + +### Périmètre géographique : + +- ✅ **Métropole** sauf ❌ Alsace-Moselle ; +- ✅ **DROM-COM** sauf ❌ les associations de Nouvelle-Calédonie, de la Polynésie française et de Wallis-et-Futuna qui ne sont pas immatriculées à l’INSEE, mais dans des bases locales + +### Actualisation de la donnée + +Les données sont mises à jour quotidiennement : +- Les créations et modifications validées par les greffes des associations sont déversées et disponibles le lendemain dans le RNA. Les données du RNA sont transmises deux fois par jour à la DJEPVA pour être intégrées dans cette API. +- Pour le répertoire Sirene, la mise à jour des données est faite quotidiennement entre 0h et 3h à l’Insee. + +## Modalités d'appel + +Cette API est appelable avec le SIRET de l'établissement + +## Les données + +Cette API délivre ... + +Informations renvoyées en JSON : + + +| Donnée | Exemple | Description | +| -------------- | ------------------ | ------------------------ | +| Nom de l'association | `Sport pour tous` | Il s'agit du nom de l'association tel que figurant sur ... | +| Date de création | `2023-08-31` | Délivrée au format | + +## 🔎 En savoir plus +- API XXX +- API XXX + + diff --git a/_data/api/template.api-opendata.md.example b/_data/api/template.api-opendata.md.example new file mode 100644 index 000000000..d0f53fe5a --- /dev/null +++ b/_data/api/template.api-opendata.md.example @@ -0,0 +1,94 @@ +--- +title: API XXX # 📍 Nom commercial de l'API, privilégier un nom court. +tagline: Interrogez l'API ... # 📍 Une phrase pour résumer le service rendu par l'API. +producer: identifiant_fournisseur # 📍 Identifiant du fournisseur de la donnée trouvable ou ajoutable dans le dossier `api_gouv/_data/producteurs`, pour en savoir plus consulter le read.me. +contact_link: contact@contact.fr # 📍 Adresse e-mail que les usagers peuvent utiliser pour vous contacter. +partners: # Liste des co-producteurs de l'API + - dinum # Sera cliquable vers une page détaillant le partenaire car fait partie des fournisseurs référencés dans le dossier `api_gouv/_data/producteurs` + - partenaire # Sera listé sans être cliquable. +is_open: 1 # 📍 1 si l'API est entièrement ouverte, 0 si un compte est nécessaire pour utiliser l'API. +account_link: https://site-api/user/register # URL de la page de demande d'habilitation si l'API nécessite un compte pour être utilisée. +rate_limiting_resume: 10 appels / minute / IP # 📍 Volumétrie maximale de votre API. +rate_limiting_description: | + L'API est disponible à hauteur de 10 appels par minutes. +# Phrase descriptive de la volumétrie +doc_tech_link: https://swagger/api/open-api.yml # 📍 URL qui donne accès au swagger de votre API, sur la page API.gouv suivante : https://api.gouv.fr/documentation, accessible depuis le bouton "Tester l'API" sur la fiche de l'API. Pour en savoir plus, consulter le read.me. +doc_tech_external: https://doc-tech-de-votre-site.fr # 📍 URL vers la documentation technique de l'API +monitoring_link: https://page-statut-de-lapi # URL de la page de statut de l'API +stats_detail_resume: Les statistiques sont disponibles en temps réel # Résumer en un titre à quoi peut s'attendre l'usager en termes de statistiques de consommation de l'API. Cette phrase suit le titre "Stats:" qui permet de déplier un volet avec les détails ci-dessous (description et lien) : +stats_detail_description: | + Accédez au suivi des consommations de l'API +stats_detail_link: http://page-stats-dusage-de-lapi # URL de la page des statistiques d'usage de l'API +themes: # 📍 Ajouter un ou plusieurs thèmes, qui permettront aux usagers de trouver votre API en filtrant le catalogue par thématique. Pour ajouter un thème ci-dessous, supprimer simplement le # (sans retirer des blancs.) +# - Administration +# - Administration & législation +# - Agriculture +# - Culture +# - Droit & Justice +# - Education +# - Emploi +# - Energie +# - Entreprise +# - Environnement +# - Géographie +# - Particulier +# - Professionnels +# - Santé +# - Sécurité +# - Transport +keywords: # 📍 Ajouter des mots clés qui permettront aux usagers de trouver votre API avec le moteur de recherche. + - associations + - rna +last_update: 11/10/2023 # Date de la dernière mise à jour de la doc +datagouv_uuid: # Si l'API se base sur un jeu de données ouvertes accessibles depuis data.gouv.fr, ajouter l'uuid du jeu de données pour afficher automatiquement un bloc en fin de page référençant le jeu de données. +content_intro: | + ### À quoi sert l'API XXX ? + + L'API XXX délivre les informations et documents de référence de XXX, informations issues du répertoire XXX et de la base YYY. +# 📍 Ce champ apparaîtra en haut de la fiche de l'API, sous le titre description. Le texte ci-dessus est un exemple et montre comment ajouter un lien vers l'extérieur. + +--- + + +## Périmètre de l'API + +### Entitées concernés : + +Cette API concerne ✅ **les associations inscrites au répertoire national des associations (RNA) et/ou au répertoire Sirene**. + +Cette API ne concerne pas : +- ❌ les associations du régime Alsace-Moselle ; +- ❌ les associations XX. + +### Périmètre géographique : + +- ✅ **Métropole** sauf ❌ Alsace-Moselle ; +- ✅ **DROM-COM** sauf ❌ les associations de Nouvelle-Calédonie, de la Polynésie française et de Wallis-et-Futuna qui ne sont pas immatriculées à l’INSEE, mais dans des bases locales + +### Actualisation de la donnée + +Les données sont mises à jour quotidiennement : +- Les créations et modifications validées par les greffes des associations sont déversées et disponibles le lendemain dans le RNA. Les données du RNA sont transmises deux fois par jour à la DJEPVA pour être intégrées dans cette API. +- Pour le répertoire Sirene, la mise à jour des données est faite quotidiennement entre 0h et 3h à l’Insee. + +## Modalités d'appel + +Cette API est appelable avec le SIRET de l'établissement + +## Les données + +Cette API délivre ... + +Informations renvoyées en JSON : + + +| Donnée | Exemple | Description | +| -------------- | ------------------ | ------------------------ | +| Nom de l'association | `Sport pour tous` | Il s'agit du nom de l'association tel que figurant sur ... | +| Date de création | `2023-08-31` | Délivrée au format | + +## 🔎 En savoir plus +- API XXX +- API XXX + + diff --git a/_data/producteurs/template.fournisseur.md.example b/_data/producteurs/template.fournisseur.md.example new file mode 100644 index 000000000..5db70235f --- /dev/null +++ b/_data/producteurs/template.fournisseur.md.example @@ -0,0 +1,25 @@ +--- +name: Direction interministérielle du numérique # Nom long qui figure sur les cartes des API dans le catalogue +acronym: DINUM # Nom court ou acronyme qui figure sur les pages des API. +nameWithPronoun: la DINUM +logo: dinum.png +type: Etablissement public # Choisir parmi les élément suivants : Etablissement public | Groupement d'intérêt public | Collectivité | Département | Autre | Ministère | Juridiction | +site: https://numerique.gouv.fr # URL du site officiel du fournisseur +short: Service de la Première ministre, placé sous l’autorité du ministre de la Transformation et de la Fonction publiques, la direction interministérielle du numérique (DINUM) a pour mission d’élaborer la stratégie numérique de l’État et de piloter sa mise en œuvre. # Description courte répondant à la question "Qu'est ce que le «fournisseur de données» ?" +description: | + La DINUM oeuvre pour un État plus efficace, plus simple et plus souverain grâce au numérique. + Les missions de la DINUM sont fixées par décret (décret du 25 octobre 2019, modifié par le décret du 22 avril 2023). + - Mission 1 + - Mission 2 + - Etc. +# Description longue répondant à la question "Quelle est sa mission de service public ?" +data: | + | Donnée | Description | + | ------------------ | ------------------------------ | + | Hydrométrie | mesure du débit des cours d'eau | +# Tableau listant les données détenues par le fournisseur +contact: https://contact.service.gouv.fr/ # URL de la page de contact du fournisseur. +annuaire: https://lannuaire.service-public.fr/ #URL vers l'annuaire du service public +siteOpenData: https://www.data.gouv.fr/fr/organizations/ # URL du site dédié à l'OpenData du fournisseur de données, peut renvoyer vers le site data.gouv +siteAPI: https:// # URL du site officiel dédié aux API du fournisseur +--- diff --git a/model/readOnDiskForNode.js b/model/readOnDiskForNode.js index 416fc5a37..e73510945 100644 --- a/model/readOnDiskForNode.js +++ b/model/readOnDiskForNode.js @@ -6,7 +6,7 @@ const { formatProducteur } = require('./formatters/producteur'); const fs = require('fs'); const readAllApisOnDisk = async () => { - const files = fs.readdirSync('./_data/api', 'utf8'); + const files = fs.readdirSync('./_data/api', 'utf8').filter(fileName => fileName.endsWith('.md')); const allProducers = await readAllProducersOnDisk(); const formatter = formatApiWithOwner(allProducers); @@ -19,7 +19,7 @@ const readAllApisOnDisk = async () => { }; const readAllServicesOnDisk = async () => { - const files = fs.readdirSync('./_data/service', 'utf8'); + const files = fs.readdirSync('./_data/service', 'utf8').filter(fileName => fileName.endsWith('.md')); const allApis = await readAllApisOnDisk(); const formatter = formatServiceWithApis(allApis); @@ -32,7 +32,7 @@ const readAllServicesOnDisk = async () => { }; const readAllGuidesOnDisk = async () => { - const files = fs.readdirSync('./_data/guides', 'utf8'); + const files = fs.readdirSync('./_data/guides', 'utf8').filter(fileName => fileName.endsWith('.md')); return files.map(fileName => { const file = fs.readFileSync(`./_data/guides/${fileName}`, 'utf8'); @@ -43,7 +43,7 @@ const readAllGuidesOnDisk = async () => { }; const readAllProducersOnDisk = async () => { - const files = fs.readdirSync('./_data/producteurs', 'utf8'); + const files = fs.readdirSync('./_data/producteurs', 'utf8').filter(fileName => fileName.endsWith('.md')); return files.map(fileName => { const file = fs.readFileSync(`./_data/producteurs/${fileName}`, 'utf8');