Bonjour ! Nous allons travailler ensemble, le présent document vous permettra de cerner nos attentes et recommandations.
Faisons connaissance, et faisons tourner 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.
Objet : prise de contact Destinataires : contact@apientreprise.fr,
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 dateX à dateY Insérer numéro de tel ou etre joint 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
Nommage, domaine, hébergement
Qualité de service Taux de disponibilité
Règles de maintenance et évolution
- https uniquement
- le token est en paramètre, pas dans l'url
- utiliser un sous domaine réservé api.mondomaine.com
- respecter la pluralisation => api_path/users/:id
- utiliser le versionnage d'api pour anticiper les futures évolutions api.mondomaine.com/v1/ ...
- REST + CRUD autant que possible
- 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 mis à null
- Un champ vide est laissé a null au lieu d'être mis à ''
- Indications de temps de réponse fournie pour régler le timeout
- Protocole de sécurité bien décrit, OAuth2 autant que possible
- 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
Documentation
- 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)
- Les limites de volumétrie sont décrites
- Les limitations afférentes au copyright, à la CNIL et/ou a toute autre contraintes légale 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