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.