Bonjour ! Nous allons travailler ensemble, le présent document vous permettra de cerner nos attentes et recommandations.
Faisons connaissance, et échangeons les contacts des responsables techniques pour adresser les emails aux destinataires concernés ainsi que leurs fonctions. Il est bon de mieux se connaitre avant de travailler ensemble, cela permet aussi d'indiquer vos disponibilités et indisponibilités futures.
Voici un exemple de mail de prise de contact permettant de bien démarrer le projet.
Objet : prise de contact Destinataires : tech@entreprise.api.gouv.fr, emails de vos collegues
Bonjour ici Nom, Prénom. Je m'occupe de Responsabilités en rapport avec le projet. Je suis disponible un peu | beaucoup | à la folie (rayez la mention inutile) de date X à date Y. Je suis joignable au numéro de téléphone en cas d'urgence.
Chaque api a ses contraintes propres et son exposition n'est pas toujours grand public. Fournissez nous des instructions qui doivent marcher après un simple copié collé. Un exemple d'utilisation de curl pour récuprer les issues de redmine un software de gestion de bugs en ligne
curl -v -H "Content-Type: application/json" \
-X PUT --data-binary "@388.json" -u login:password http://redmine/issues/388.json
Cela nous permet de valider que nous sommes capables techniquement d'accéder à l'API et de récupérer des données
APIEntreprise aggrège plusieurs API et jeux de données différents. Sa qualité est donc égale à celle de la moins bonne API que nous intégrons. Nous apportons donc un soin tout particulier et sommes vigileants sur toute API nouvelle à intégrer. De grandes attentes de notre part signifient que nous sommes prêts à aider. Sans plus attendre, c'est parti :
Vos APIs sont versionnées, et cela se voit dans les URLs exposées (cf format des urls). Les évolutions de version avec leurs eventuels breaking change sont communiquées en amont à tech@entreprise.api.gouv.fr. Un message deprecated est introduit sur les morceaux d'API qui vont bientot évoluer.
- REST + CRUD autant que possible https://fr.wikipedia.org/wiki/Representational_state_transfer
- respecter la pluralisation => _path/users/:id
- La version est comprise dans les URLs et se trouve après le domaine mais avant les ressources exposées api.mondomaine.com/v1/ ...
- Https uniquement
- Le token est en paramètre, pas dans l'URL
- Utiliser un sous domaine réservé api.mondomaine.com qui redirige vers une application dédiée
- Protocole de sécurité bien décrit
- OAuth2 si autant que possible si cela fait sens (probablement pas à court terme)
- Les maintenances sont programmées à l'avance et communiquées à tech@apientreprise.fr
- Le service atteint 99% de disponibilité en rodage puis supérieur à 99.5% en régime de croisière. Redonder si possible le service dans des datacenters / infrastructures différents.
- Codes d'erreur lisibles et standards https://fr.wikipedia.org/wiki/Liste_des_codes_HTTP (éviter un 200 Ok avec un body qui contient l'erreur)
- Une réponse contient tous ses champs mêmes vides qui sont alors mis à null
- Un champ vide est laissé a null au lieu d'être mis à ''
- Préférence pour les réponses en json avec champs en snake case par exemple siret siege social => siret_siege_social
- Pas d'accents ou de caracteres speciaux, les noms de champs sont en minuscules
- Les booléens sont indiqués à true / false
- Les dates sont exposées sous forme de timestamp (nombre de secondes depuis EPOCH 1/1/1970 GMT:00). C'est un integer
Il est possible d'utiliser http://gist.github.com pour mettre en ligne sa documentation et gérer ses mises à jour. Cette plateforme propose d'ailleurs un mode secret permettant aux API sensibles de ne pas avoir leur documentation exposée aux 4 vents.
- La documentation est à jour
- Les cas d'erreurs courants sont décrits
- La documentation est disponible en ligne et présente des exemples divers et variés
- Les cas particuliers sont bien documentés (entrées legacy dans la BDD derrière l'api, URLs non REST)
- Les limites de volumétrie tolérée sont décrites
- Les limitations afférentes au copyright, à la CNIL et/ou a toute autre contraintes légales sur les données sont décrites quitte a dire qu'elles sont inexistantes
- La fréquence de mise a jour des données est indiquée pour permettre un cache de notre côté qui soulage vos APIs
- Il existe une documentation qui suit les versions de l'API
- Indications de temps de réponse fournie pour nous permettre de régler le timeout
Nous gardons trace des appels passés via notre plateforme à vos APIs si ceux ci demandent des données sensibles. Un dashboard est disponible ici : https://dashboard.entreprise.api.gouv.fr/ Moult améliorations de ce dashboard sont possibles, n'hésitez pas a nous faire part de vos suggestions. Aidez nous à vous aider à vendre les projets API.
Nous sommes là pour clarifier le présent document et vous aider à comprendre nos attentes, les expliquer, les remettre en question si nécessaire ainsi que pour fournir une assistance à maitrise d'ouvrage sur vos APIs si vous souhaitez les mettre en conformité avec les bonnes pratiques décrites ici. Adressez nous toute remarque, questions intelligentes ou bêtes, messages d'amour, de feedback à tech@apientreprise.fr
Bonne journée et merci pour votre temps !
Salut !
Je trouve que les titres ne sont pas super parlants dans la partie "En selle !". Par exemple "Jeu de tests / installation", c'est "Comment nous envoyer un jeu de tests" "Comment récupérer notre jeu de tests" ou "Comment nous fournir un jeu de tests dans le mail de contact" ?
Le template du mail serait plus propre avec un peu de markdown pour les
parties variables.Pour le reste, j'aime bien le format checklist, c'est très clair !