5 règles d'or pour une excellente conception d'API Web

Vous êtes-vous déjà demandé « à quoi pensaient-ils ? » lors de l'intégration d'un service web via son API ? Sinon, vous avez eu beaucoup plus de chance que moi.

Tout développeur de logiciels sait à quel point il est facile de laisser un projet se transformer en code spaghetti, et les API Web ne sont pas moins susceptibles de créer un Web enchevêtré. Mais cela n'a pas besoin d'être ainsi. En vérité, il est possible de concevoir d' excellentes API Web que les gens apprécieront réellement d'utiliser et que vous apprécierez également de créer. Mais comment? La réponse à cette question est de quoi parle cet article.

La perspective

La plupart du temps, lorsque vous créez des solutions, vous concevez pour des utilisateurs finaux qui ne sont pas des programmeurs ou qui ne sont généralement pas techniquement sophistiqués. Vous leur donnez une interface graphique et, si vous avez bien fait votre travail, vous avez glané une assez bonne idée d'eux de ce qu'ils ont besoin de l'interface pour faire.

Mais le développement d'API est différent. Vous concevez une interface pour les programmeurs , probablement sans même savoir qui ils sont. Et quels qu'ils soient, ils auront la sophistication technique (ou du moins penseront qu'ils ont la sophistication technique) pour signaler chaque petit défaut de votre logiciel. Vos utilisateurs sont susceptibles d'être aussi critiques à l'égard de votre API que vous le seriez à l'égard des leurs, et prendront beaucoup de plaisir à la critiquer.

Et c'est là une partie de l'ironie, soit dit en passant. Si quelqu'un doit comprendre comment créer une API Web facile à utiliser, c'est bien vous . Après tout, vous êtes un ingénieur logiciel, tout comme les utilisateurs de votre API, vous partagez donc leur point de vue. Pas vous ?

Eh bien, même si vous comprenez certainement leur point de vue, vous ne partagez pas nécessairement leur point de vue. Lorsque vous développez ou améliorez votre API, vous avez le point de vue d'un concepteur d'API alors qu'il a le point de vue d'un utilisateur d'API .

Les concepteurs d'API se concentrent généralement sur des questions telles que "Que doit faire ce service ?" ou "Que doit fournir ce service ?" , tandis que les utilisateurs de l'API se concentrent sur "Comment puis-je utiliser cette API pour faire ce dont j'ai besoin ?" , ou plus précisément, "Comment puis-je déployer le strict minimum d'efforts pour obtenir ce dont j'ai besoin de cette API ?" .

Ces différentes questions conduisent à deux perspectives très différentes. Par conséquent, la condition préalable nécessaire à la conception d'une excellente API est de déplacer votre point de vue de celui du concepteur d'API vers celui de l'utilisateur de l'API. En d'autres termes, posez-vous continuellement les questions que vous vous poseriez naturellement si vous étiez votre propre utilisateur. Plutôt que de penser à ce que votre API peut faire, réfléchissez aux différentes manières dont elle peut avoir besoin ou souhaite être utilisée , puis concentrez-vous sur la simplification de ces tâches pour les utilisateurs de votre API.

Bien que cela puisse sembler simple et évident, il est étonnant de constater à quel point les API semblent rarement conçues de cette manière. Pensez aux API que vous avez rencontrées dans votre carrière. À quelle fréquence semblent-ils avoir été conçus dans cette perspective ? La conception d'API Web peut être difficile.

Cela dit, continuons et parlons des 5 règles d'or pour concevoir une excellente API Web , à savoir :

1. Documentation
2. Stabilité et cohérence
3. Souplesse
4. Sécurité
5. Facilité d'adoption

Règle 1 : Documents

Documentation. Oui, je commence ici.

Vous détestez la documentation ? Eh bien, je peux compatir, mais mettez votre chapeau "perspective utilisateur" et je parie que la seule chose que vous détestez plus que d'avoir à écrire de la documentation est d'avoir à essayer d'utiliser une API non documentée. Je repose mon dossier.

L'essentiel est que, si vous voulez que quelqu'un utilise votre API, la documentation est essentielle. Vous devez simplement bien faire les choses. C'est la première chose que les utilisateurs verront, donc à certains égards, c'est comme l'emballage cadeau. Présentez-vous bien, et les gens sont plus susceptibles d'utiliser votre API et de supporter toutes les idiosyncrasies.

Alors, comment rédiger une bonne documentation ?

La partie relativement simple consiste à documenter les méthodes API elles-mêmes ; c'est-à-dire, des exemples de demandes et de réponses, ainsi que des descriptions de chacun des éléments dans les deux. Heureusement, il existe un nombre croissant d'outils logiciels qui facilitent et simplifient la tâche de génération de documentation. Ou vous pouvez écrire vous-même quelque chose qui introspecte votre API, vos points de terminaison et vos fonctions, et génère la documentation correspondante pour vous.

Mais ce qui sépare une excellente documentation d'une documentation adéquate, c'est l'inclusion d'exemples d'utilisation et, idéalement, de didacticiels. C'est ce qui aide l'utilisateur à comprendre votre API et par où commencer. Il les oriente et les aide à charger votre API dans leur cerveau.

Par exemple, si les développeurs de Twilio répertorient chaque classe, chaque méthode et chaque réponse possible à leur API, mais n'ont pas pris la peine de mentionner que vous pouvez envoyer un SMS, suivre un appel ou acheter un numéro de téléphone via leur API, il faudrait beaucoup de temps à l'utilisateur de l'API pour trouver ces informations et les comprendre de manière cohérente. Pouvez-vous imaginer trier un arbre géant de classes et de méthodes sans aucune idée de ce à quoi elles servaient, autre que leur nom ? Cela semble terrible, non ? Mais c'est exactement ce que font tant de fournisseurs d'API, laissant ainsi leurs API opaques à tout le monde sauf à eux-mêmes. Le guide du développeur et de l'API Rackspace CloudFiles en est un exemple ; il est difficile de s'orienter à moins de comprendre déjà ce qu'ils font et ce qu'ils fournissent.

Alors écrivez des tutoriels concis qui aident le développeur à être opérationnel rapidement, avec au moins un squelette de ce qu'il essaie de faire, puis orientez-les vers la liste de fonctionnalités plus détaillée et entièrement documentée afin qu'ils puissent se développer sur ce qu'ils ont.

Une fois que vous avez terminé avec votre documentation, assurez-vous de valider qu'elle a du sens pour des personnes autres que vous-même. Envoyez-le à d'autres développeurs de votre réseau, ne leur donnez aucune instruction autre que de les diriger vers la documentation et demandez-leur de suivre un didacticiel ou de créer quelque chose de vraiment basique en 15 minutes environ. S'ils ne peuvent pas avoir une intégration de base avec votre API en 15 minutes, vous avez plus de travail à faire.

Pour des exemples remarquables de documentation excellente et détaillée, consultez Twilio, Django et MailChimp. Aucun de ces produits n'est nécessairement le meilleur sur leurs marchés (bien qu'ils soient tous de bons produits), mais ils se distinguent en fournissant une des meilleures documentations sur leurs marchés, ce qui a certainement facilité leur large acceptation et leur part de marché.

Règle 2 : Stabilité et cohérence

Si vous avez déjà utilisé l'API de Facebook, vous savez à quelle fréquence ils déprécient et réécrivent complètement leurs API. Peu importe à quel point vous respectez leur culture de hacker ou leur produit, leur point de vue n'est pas favorable aux développeurs. La raison pour laquelle ils réussissent toujours est parce qu'ils ont un milliard d'utilisateurs, pas parce que leur API est géniale.

Mais vous n'avez probablement pas le luxe d'avoir une base d'utilisateurs et une part de marché aussi gigantesques, vous aurez donc besoin d'une API beaucoup moins volatile, gardant les anciennes versions en cours d'exécution et prises en charge pendant une assez longue période. Peut-être même des années. Donc, à cette fin, voici quelques trucs et astuces.

Disons par exemple que votre API est accessible via l'URL http://myapisite.com/api/widgets et fournit sa réponse au format JSON. Bien que cela puisse sembler correct à première vue, que se passe-t-il lorsque vous devez modifier le format de la réponse JSON ? Tous ceux qui sont déjà intégrés avec vous vont craquer. Oups.

Planifiez donc à l'avance et versionnez votre API dès le départ, en incorporant explicitement un numéro de version dans l'URL (par exemple, http://myapisite.com/api/widgets?version=1 ou http://myapisite.com/api/widgets/v1 ) afin que les utilisateurs puissent compter sur le fonctionnement de la version 1 et puissent mettre à niveau vers n'importe quelle version ultérieure lorsqu'ils sont prêts à le faire. Si vous avez besoin de supprimer progressivement une version antérieure à un moment donné, allez-y, mais donnez un préavis suffisant et proposez une sorte de plan de transition.

Un bon schéma d'URL inclura les versions majeures dans l'URL. Toute modification du format de sortie ou des types de données pris en charge doit entraîner le passage à une nouvelle version majeure. Généralement, il est acceptable de conserver la même version si tout ce que vous faites est d'ajouter des clés ou des nœuds à votre sortie, mais pour plus de sécurité, chaque fois que la sortie change, modifiez une version.

En plus d'être stables dans le temps, les API doivent être cohérentes en interne. J'ai vu de nombreuses API qui modifient les noms de paramètres ou les méthodes de publication des données, en fonction du point de terminaison utilisé. Au lieu de cela, vous devez gérer les paramètres communs globalement au sein de votre API et utiliser l'héritage ou une architecture partagée pour réutiliser les mêmes conventions de dénomination et la gestion des données de manière cohérente dans votre API.

Enfin, vous devez enregistrer et publier un journal des modifications pour montrer les différences entre les versions de votre API afin que les utilisateurs sachent exactement comment effectuer la mise à niveau.

Règle 3 : Flexibilité

Garbage in, garbage out (GIGO) est un mantra bien connu de la plupart des programmeurs. Appliqué à la conception d'API Web, ce principe directeur tend à dicter une approche assez rigide pour demander la validation. Ça sonne bien, non ? Pas de gâchis, pas de problème.

Pourtant, comme pour tout, il doit y avoir un certain équilibre. Comme il n'est pas possible d'anticiper toutes les façons dont les utilisateurs voudront utiliser votre service, et puisque toutes les plates-formes client ne sont pas cohérentes (c'est-à-dire que toutes les plates-formes n'ont pas un très bon support JSON, une bibliothèque OAuth décente, etc.), il est bon de avoir au moins un certain degré de flexibilité ou de tolérance en ce qui concerne vos contraintes d'entrée et de sortie.

Par exemple, de nombreuses API prendront en charge une variété de formats de sortie, tels que JSON, YAML, XML, etc. al., mais ne prendra en charge que la spécification du format dans l'URL elle-même. Dans un esprit de flexibilité, vous pouvez autoriser que cela soit également spécifié dans l'URL (par exemple, /api/v1/widgets.json ), ou vous pouvez également lire et reconnaître un en-tête HTTP Accept: application/json , ou prendre en charge un variable de chaîne de requête telle que ?format=JSON , etc.

Et pendant que nous y sommes, pourquoi ne pas permettre au format spécifié d'être insensible à la casse, afin que l'utilisateur puisse également spécifier ?format=json ? C'est un exemple classique d'un moyen d'atténuer la frustration inutile de l'utilisateur de votre API.

Un autre exemple est de permettre différentes manières de saisir des variables. Ainsi, tout comme vous avez une variété de formats de sortie, autorisez également une variété de formats d'entrée (par exemple, des variables POST simples, JSON, XML, etc.). Vous devriez au moins prendre en charge les variables POST standard, et de nombreuses applications modernes prennent également en charge JSON, donc ces deux sont un bon point de départ.

Le point ici est que vous ne devriez pas supposer que tout le monde partage vos préférences techniques. Avec un peu de recherche sur le fonctionnement des autres API et en dialoguant avec d'autres développeurs, vous pouvez glaner d'autres alternatives précieuses qui sont utiles et les inclure dans votre API.

Règle 4 : Sécurité

La sécurité est évidemment l'une des choses les plus importantes à intégrer à votre service Web, mais de nombreux développeurs la rendent ridiculement difficile à utiliser. En tant que fournisseur d'API, vous devez proposer des exemples utilisables sur la manière d'authentifier et d'autoriser l'accès à votre API. Cela ne devrait pas être un problème difficile sur lequel un utilisateur final passe des heures à travailler. Faites-en votre objectif soit qu'ils n'aient pas à écrire de code, soit qu'il leur faut moins de 5 minutes pour l'écrire.

Pour la plupart des API, je préfère une simple authentification basée sur des jetons, où le jeton est un hachage aléatoire attribué à l'utilisateur et ils peuvent le réinitialiser à tout moment s'il a été volé. Autorisez la transmission du jeton via POST ou un en-tête HTTP. Par exemple, l'utilisateur pourrait (et devrait) envoyer un jeton SHA-1 en tant que variable POST, ou en tant qu'en-tête dans un format tel que "Autorisation : da39a3ee5e6b4b0d3255bfef95601890afd80709".

Choisissez également un jeton sécurisé, et non un identifiant numérique court. Quelque chose d'irréversible est le meilleur. Par exemple, il est relativement simple de simplement générer un jeton SHA lors de la création de l'utilisateur et de le stocker dans la base de données. Ensuite, vous pouvez simplement interroger votre base de données pour tous les utilisateurs correspondant à ce jeton. Vous pouvez également créer un jeton généré avec un identifiant unique et une valeur de sel, quelque chose comme SHA(User.ID + "abcd123") , puis interroger tout utilisateur correspondant ; par exemple, where TokenFromPost = SHA(User.ID + "abcd123") .

Une autre très bonne option est OAuth 2 + SSL. Vous devriez de toute façon utiliser SSL, mais OAuth 2 est relativement simple à mettre en œuvre côté serveur et des bibliothèques sont disponibles pour de nombreux langages de programmation courants.

Si l'API que vous avez créée est censée être accessible sur un site Web public via JavaScript, vous devez également vous assurer de valider une liste d'URL par compte pour le jeton. De cette façon, personne ne peut aller inspecter les appels à votre API, voler le jeton à votre utilisateur et l'utiliser pour lui-même.

Voici quelques autres éléments importants à garder à l'esprit :

• Fonctionnalité de liste blanche. Les API vous permettent généralement d'effectuer des opérations de création, de lecture, de mise à jour et de suppression de base sur les données. Mais vous ne voulez pas autoriser ces opérations pour chaque entité, alors assurez-vous que chacune a une liste blanche d'actions autorisées. Assurez-vous, par exemple, que seuls les utilisateurs autorisés peuvent exécuter des commandes telles que /user/delete/<id> . De même, tous les en-têtes utiles qui sont envoyés dans la demande de l'utilisateur doivent également être validés par rapport à une liste blanche. Si vous autorisez les en-têtes de type Content, vérifiez que tout ce que l'utilisateur envoie correspond réellement à une liste while des types de contenu pris en charge. Si ce n'est pas le cas, renvoyez un message d'erreur tel qu'une réponse 406 Non acceptable. La liste blanche est importante car de nombreuses API sont générées automatiquement ou utilisent une liste noire à la place, ce qui signifie que vous devez être explicite sur ce que vous ne voulez pas . Cependant, la règle d'or de la sécurité est de commencer avec absolument rien et de n'autoriser explicitement que ce que vous voulez .

• Protégez-vous contre le Cross-Site Request Forgery (CSRF). Si vous autorisez l'authentification par session ou par cookie, vous devez vous assurer que vous vous protégez des attaques CSRF. L'Open Web Application Security Project (OWASP) fournit des conseils utiles sur les moyens d'exclure ces vulnérabilités.

• Valider l'accès aux ressources. Dans chaque demande, vous devez vérifier qu'un utilisateur est bien autorisé à accéder à l'élément spécifique auquel il fait référence. Ainsi, si vous disposez d'un point de terminaison pour afficher les détails de la carte de crédit d'un utilisateur (par exemple, /account/card/view/152423 ), assurez-vous que l'ID « 152423 » fait référence à une ressource à laquelle l'utilisateur est réellement autorisé à accéder.

• Validez toutes les entrées. Toutes les entrées d'un utilisateur doivent être analysées en toute sécurité, de préférence à l'aide d'une bibliothèque bien connue si vous utilisez des entrées compliquées comme XML ou JSON. Ne construisez pas votre propre analyseur, ou vous êtes dans un monde de souffrance.

Règle 5 : Facilité d'adoption

C'est vraiment la règle la plus importante du groupe et elle s'appuie sur toutes les autres. Comme je l'ai mentionné lors de la règle de documentation, essayez ceci avec des personnes qui découvrent votre API. Assurez-vous qu'ils peuvent être opérationnels avec au moins une implémentation de base de votre API, même s'il ne s'agit que de suivre un didacticiel, en quelques minutes. Je pense que 15 minutes est un bon objectif.

Voici quelques recommandations spécifiques pour faciliter et faciliter l'adoption de votre API :

• Assurez-vous que les gens peuvent réellement utiliser votre API et qu'elle fonctionne du premier coup, à chaque fois. Demandez à de nouvelles personnes d'essayer d'implémenter votre API de temps en temps pour vérifier qu'elle n'est pas déroutante d'une manière à laquelle vous êtes devenu immunisé.

• Rester simple. Ne faites aucune authentification sophistiquée. Ne faites pas un schéma d'URL personnalisé fou. Ne réinventez pas SOAP, ou JSON, ou REST, ou quoi que ce soit. Utilisez tous les outils que vous pouvez qui ont déjà été implémentés et sont largement acceptés, de sorte que les développeurs n'aient qu'à apprendre votre API, pas votre API + 10 nouvelles technologies obscures.

• Fournissez des bibliothèques spécifiques à la langue pour vous connecter à votre service. Il existe de bons outils pour générer automatiquement une bibliothèque pour vous, comme Alpaca ou Apache Thrift. Actuellement, Alpaca prend en charge Node, PHP, Python et Ruby. Thrift prend en charge C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi et plus encore.

• Simplifiez toute inscription nécessaire. Si vous ne développez pas d'API open source, ou s'il existe un processus d'inscription quelconque, assurez-vous que lors de l'inscription, un utilisateur est très rapidement dirigé vers un didacticiel. Et rendez le processus d'inscription complètement automatisé sans aucune interaction humaine de votre part.

• Fournir un excellent soutien. Un grand obstacle à l'adoption est le manque de soutien. Comment allez-vous gérer et répondre à un rapport de bogue ? Qu'en est-il de la documentation peu claire? Un utilisateur non averti ? Les forums, les traqueurs de bogues et l'assistance par e-mail sont des débuts fantastiques, mais assurez-vous que lorsque quelqu'un publie un bogue, vous l'abordez vraiment. Personne ne veut voir un forum de ville fantôme ou une liste géante de bogues qui n'ont pas été corrigés.

Récapitulatif de l'API Web

Les services Web et leurs API abondent. Malheureusement, la grande majorité est difficile à utiliser. Les raisons vont de la mauvaise conception au manque de documentation, en passant par la volatilité, les bogues non résolus ou, dans certains cas, tout ce qui précède.

Suivre les conseils de cet article vous aidera à vous assurer que votre API Web est propre, bien documentée et facile à utiliser. De telles API sont vraiment rares et sont donc beaucoup plus susceptibles d'être largement adoptées et utilisées.