Pour les besoin de mon projet Spoiled People (voir Projet de liste cadeaux sur GitHub), je dois monter en compétence côté API. Je suis allé voir du côté de la conférence « Bonnes pratiques des API ».
Cette conférence de 15 petites minutes est un retour d’expérience, y compris sur les ratés.
La première leçon qu’Éric Daspet a appris et nous transmet concerne la littérature et la pratique. Sans critiquer la littérature, son constat a été que d’un point de vue pragmatique, il vaut mieux s’adapter aux envies des utilisateurs (les développeurs).
Les recettes à suivre
Voici une première liste de conseils issus de cette conférence.
Internationalisation
- Toujours mettre des heures et non juste une date
Pas GMT mais en mettant un fuseau horaire que vous allez interpréter dans chaque paramètre)
Voir le commentaire d’Éric ci-dessous. - Attention aux langues : anticiper la possibilité d’avoir plusieurs langues, utiliser UTF-8 (et non de l’ISO).
Pagination
- L’offset sont de fausses bonnes idées.
- Trier les données par ordre (alphabétique, de date, d’arrivée,…) et utiliser « after | before » (plus ancien ou plus récent que tel item)
- Rendre la pagination obligatoire.
- Mettre des limites de taille avec une profondeur maximum
Un bon exemple : Twitter
Versionnement
Même si dans la littérature, le versionnement peut être vu comme une mauvaise pratique, en l’état, nous ne sommes pas forcément prêt à nous en passer. Partir du principe qu’on va se planter et, alors, qu’on fera une V2 plutôt que mettre des bouts de sparadrap.
- Prévoir un /v1 en bout d’URL dès le début
(NB : Le versionning dans les en-têtes n’est pas assez simple et ne sera pas pratique pour vos utilisateurs et donc ne servira pas)
Sécurité
- HTTP Basic Oauth
- + SSL
- imposer HTTPS
- Ne pas permettre le SSL désactivé dans le SDK (qui est recommandé)
- Clé d’API : savoir à tout moment qui fait la requête. Prévoyez-la.
Structure
- Faites de l’hypermédia mais ça ne suffit pas.
- Vos adresses doivent être « bidouillables » de façon qu’elles soient prédictives.
- Une adresse doit ressembler à un nom de fichier : pas de caractères spéciaux encodés, que des minuscules, pas de caractères accentués.
- Réduire la hiérarchie aux maximum (3 semble être la bonne pratique).
La conclusion
La clé :
- En faire peu.
- Ouvrir un maximum de champs pour plus tard.
- Faire simple.
- Utiliser les standard existants.
- Penser pragmatique.
NB : Le diaporama contient 10 bonnes pratiques supplémentaires en page 11.
Puisque c’était très mal dit dans l’intervention :
* L’idée est d’imposer des dates / heures sous forme ISO *avec* le décalage par rapport à UTC (sous la forme 2013-12-31T23:59:59+02:00 par exemple). Rien n’empêche d’imposer que l’heure soit donnée en UTC mais il faut que ce soit explicite et que le décalage horaire soit précisé (même s’il est toujours nul).
Quelques corrections :
* Utiliser de l’UTF et *pas* de l’ISO
* Le versionnement de l’API est généralement vu comme une *mauvaise* pratique, mais je considère que vouloir s’en passer est utopique
Merci pour ces précisions.
J’ai pris les corrections en compte (celle sur l’ISO rassure beaucoup Jean-François !)