CONTRIBUTING.md

Améliorer le site public des API des administrations

Ajouter une API

En un clic par l'interface web de GitHub 😃

Sinon, offline : créer un nouveau fichier de description dans le dossier _api et renseigner les informations en prenant exemple sur un fichier de description existant déjà dans ce dossier.

Nous vous recommandons de :

• Fournir la documentation au format OpenAPI.
• Décrire de manière claire et concise les modalités d'accès à l'API (CGU, licence…).
• Donner des exemples pertinents démontrant des utilisations réelles de l'API.
• Fournir des statistiques publiques donnant des mesures d'impact (par exemple : nombre de courses de taxi, de pièces justificatives non réclamées…).

Dans le cas d'API fermées :

• Rendre accessible un environnement « bac à sable » permettant de tester l'API.
• Automatiser et simplifier autant que possible la procédure d'enrôlement.

Ajouter un service

En un clic par l'interface web de GitHub 😃

Sinon, offline : créer un nouveau fichier de description dans le dossier _service et renseigner les informations en prenant exemple sur un fichier de description existant déjà dans ce dossier.

Éditer la description d'une API

Modifier le fichier de description de l'API dans le dossier _api.

Modifier le contenu éditorial

Rechercher le contenu à modifier et éditer le fichier correspondant.

Modifier les types d'API

Mettre à jour la propriété api_category dans _config.yml.

Modifier les exemples de recherches

Mettre à jour la propriété searchExamples dans index.html.

Modifier la présentation du site

Ce site est construit avec Jekyll, un générateur de sites statiques. La version utilisée est celle actuellement en production sur GitHub Pages.

Pour l'améliorer, les informations dans le README.md permettent d'installer la platforme en local.

Les fichiers pertinents pour une modification de la présentation sont probablement dans les dossiers _layouts et css.

Modifier le logo

La source du logo est dans le répertoire _sources. Il s'agit d'un SVG contenant du texte. Pour le rendre accessible à tous les utilisateurs, il importe de le transformer en un SVG contenant des path.

Cela peut être fait à la ligne de commande avec Inkscape :

inkscape --export-text-to-path `pwd`/_sources/logo.svg -l `pwd`/img/logo.svg

Déploiement

Prévisualisation (staging)

Chaque pull request est déployée dans Heroku, une fois le build passé. Une notification est envoyée sur la pull request :

Vous pouvez suivre le lien de la notification pour accéder à la version de l'application correspondant à la pull request.

Production

Ce site est déployé en continu avec Github Pages.

Pousser sur master, c’est partager avec le monde… ce qui signifie donc qu'il faut être très prudent avec ce pouvoir et privilégier l'usage de pull requests 😉