Tu t'es déjà demandé 'a quoi pensaient-ils?' lors de l'intégration d'un service web via son API? Sinon, vous avez été beaucoup plus chanceux que moi.
Tout développeur de logiciel sait à quel point il est facile de laisser un projet se transformer en code spaghetti, et les API Web ne sont pas moins enclines à créer un Web enchevêtré. Mais cela n’a pas besoin d’être ainsi. En vérité, il est possible de concevoir génial API Web que les gens prendre plaisir et que vous aimerez également créer. Mais comment? La réponse à cette question est de savoir en quoi consiste cet article.
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 leur avez glané une assez bonne idée de ce qu'ils ont besoin de l'interface pour faire.
Mais Développement d'API est différent. Vous concevez une interface pour programmeurs , probablement sans même savoir qui ils sont. Et qui 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 de la leur et apprécieront pleinement de la critiquer.
Et c'est là une partie de l'ironie, d'ailleurs. Si n'importe qui doit comprendre comment créer une API Web facile à utiliser, c'est tu . Après tout, vous êtes un ingénieur logiciel comme les utilisateurs de votre API, vous partagez donc leur point de vue. Pas toi?
Eh bien, alors que vous certainement comprendre leur point de vue, vous n’avez pas forcément partager leur point de vue. Lorsque vous développez ou améliorez votre API, vous avez la perspective d'une API designer alors qu'ils ont la perspective d'une API utilisateur .
Concepteurs d'API se concentrent généralement sur des questions comme «Que doit faire ce service?» ou «Que doit fournir ce service?» , tandis que 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épenser le minimum d'efforts pour tirer le meilleur parti de cette API?' .
Ces différentes questions conduisent à deux perspectives très différentes. En conséquence, la condition préalable nécessaire à la conception d'un génial L'API consiste à 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 pouvez faire, pensez aux différentes façons dont il peut avoir besoin ou vouloir être utilisé puis concentrez-vous sur la simplification au maximum de ces tâches pour les utilisateurs de votre API.
Bien que cela puisse paraître 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 au cours de votre carrière. À quelle fréquence semblent-ils avoir été conçus avec cette perspective à l'esprit? La conception d'API Web peut être difficile.
Cela dit, continuons et parlons de la 5 règles d'or pour concevoir une excellente API Web , à savoir:
Documentation. Oui, je commence ici.
Détestez-vous la documentation? Eh bien, je peux comprendre, mais mettez votre chapeau de «point de vue de l'utilisateur» et je parie que la seule chose que vous détestez plus que d'avoir à écrire de la documentation est d'essayer d'utiliser une API non documentée. Je repose mon cas.
L'essentiel est que, si vous voulez que quelqu'un utilise votre API, la documentation est essentielle. Vous devez simplement faire les choses correctement. C’est la première chose que les utilisateurs verront. À certains égards, c’est comme l’emballage cadeau. Présentez bien, et les gens sont plus susceptibles d'utiliser votre API et de supporter toutes les particularités.
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 des 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.
les acheteurs sont sensibles au prix lorsque l'acheteur réalise de faibles bénéfices.
Mais ce qui sépare une excellente documentation d'une documentation adéquate 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 devaient lister chaque classe, chaque méthode et chaque réponse possible à leur API, mais je n'ai 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, cela prendrait vraiment un longtemps pour l'utilisateur de l'API de trouver ces informations et de 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 ont été utilisées, à part leur nom? Cela semble terrible, non? Mais c’est exactement ce que font tant de fournisseurs d’API, laissant ainsi leurs API opaques pour quiconque sauf eux-mêmes. La Guide du développeur et de l'API Rackspace CloudFiles en est un exemple; il est difficile de se repérer si vous ne comprenez pas déjà ce qu’ils font et ce qu’ils fournissent.
Rédigez donc des didacticiels concis qui aident le développeur à être opérationnel rapidement, avec au moins un squelette de ce qu'il essaie de faire, puis orientez-le vers la liste de fonctionnalités plus détaillée et entièrement documentée afin qu'il puisse 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 encore du travail à faire.
Pour quelques 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é.
Si vous avez déjà utilisé API de Facebook , vous savez à quelle fréquence ils abandonnent et réécrivent complètement leurs API. Peu importe à quel point vous respectez leur culture de hackers ou leur produit, le leur n'est pas une perspective conviviale pour les 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 excellente.
Mais vous n'avez probablement pas le luxe d'une base d'utilisateurs et d'une part de marché aussi gigantesques, vous allez donc avoir besoin d'une API beaucoup moins volatile, permettant aux anciennes versions de fonctionner et d'être prises en charge pendant une période assez longue. 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 à vous vont rompre. Oops.
Alors faites un peu de planification à l'avance, et versez 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 gens puissent compter sur la version 1 et peuvent passer à toute version ultérieure lorsqu'ils sont prêts à le faire. Si vous avez besoin de supprimer progressivement une version précédente à un moment donné, allez-y, mais prévenez-le et proposez une sorte de plan de transition.
Un bon schéma d'URL inclura des 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. En règle générale, 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 être prudent, à chaque fois que la sortie change, remplacez 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 des données POSTing, en fonction du point de terminaison utilisé. Au lieu de cela, vous devez gérer les paramètres communs de manière globale dans 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 l'ensemble de votre API.
Enfin, vous devez enregistrer et publier un journal des modifications pour afficher les différences entre les versions de votre API afin que les utilisateurs sachent exactement comment mettre à niveau.
En relation: Tutoriel Grape Gem: Comment créer une API de type REST dans RubyGarbage 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 la validation des demandes. Ça sonne bien, non? Pas de gâchis, pas de problème.
Pourtant, comme pour tout, il faut un équilibre. Comme il n'est pas possible d'anticiper toutes les manières dont les utilisateurs voudront utiliser votre service, et comme toutes les plates-formes clientes 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 par rapport à 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, et. al., mais ne prendra en charge que la spécification du format dans l'URL elle-même. Dans l'esprit de rester flexible, 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 Accept: application/json En-tête HTTP, ou prenez en charge une variable de chaîne de requête telle que ?format=JSON, etc.
Et tant que nous y sommes, pourquoi ne pas autoriser le format spécifié à être insensible à la casse, afin que l'utilisateur puisse spécifier ?format=json ainsi que? Il s’agit d’un exemple classique de moyen de soulager 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 éléments sont un bon point de départ.
Le fait est que vous ne devez 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 intéressantes qui sont utiles et les inclure dans votre API.
La sécurité est évidemment l'une des choses les plus importantes à intégrer à votre service Web, mais tant de développeurs le rendent ridiculement difficile à utiliser. En tant que fournisseur d'API, vous devriez proposer des exemples utilisables sur la façon d'authentifier et d'autoriser lors de 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 sorte qu'ils n'aient pas à écrire de code ou que cela leur prenne moins de 5 minutes pour l'écrire.
Pour la plupart des API, je préfère un simple authentification basée sur les jetons , où le jeton est un hachage aléatoire attribué à l'utilisateur et il peut le réinitialiser à tout moment s'il a été volé. Autorisez le jeton à être transmis 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é, pas un identifiant numérique court. Quelque chose d'irréversible est préférable. 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 qui correspond; Par exemple, where TokenFromPost = SHA(User.ID + 'abcd123').
Une autre très bonne option est OAuth 2 + SSL . Vous devriez quand même utiliser SSL, mais OAuth 2 est raisonnablement simple à implémenter 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 choses importantes à garder à l'esprit:
Fonctionnalité de liste blanche. Les API vous permettent généralement d'effectuer des opérations de base de création, de lecture, de mise à jour et de suppression sur les données. Mais vous ne souhaitez pas autoriser ces opérations pour chaque entité. Assurez-vous donc que chacune dispose d'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/. De même, tous les en-têtes utiles 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 Contenu, vérifiez que tout ce que l'utilisateur envoie correspond réellement à une liste blanche de types de contenu pris en charge. Si ce n’est pas le cas, renvoyez un message d’erreur tel qu’une réponse 406 Not 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 pas vouloir. 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 faire vouloir.
comment collecter des données sur twitter
Protégez-vous contre Falsification de requêtes intersites (CSRF) . Si vous autorisez l'authentification de session ou par cookie, vous devez vous assurer que vous vous protégez contre les attaques CSRF. La Ouvrir le projet de sécurité des applications Web (OWASP) fournit des conseils utiles sur moyens d'éviter ces vulnérabilités .
Validez l'accès aux ressources. Dans chaque demande, vous devez vérifier qu'un utilisateur est en fait autorisé à accéder à l'élément spécifique auquel il fait référence. Par conséquent, 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 en utilisant une bibliothèque bien connue si vous utilisez des entrées compliquées telles que XML ou JSON. Ne construisez pas votre propre analyseur, ou vous êtes dans un monde de souffrance.
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 ne connaissent pas votre API. Assurez-vous qu'ils peuvent être opérationnels avec au moins une implémentation de base de votre API, même si cela ne fait que suivre un tutoriel, 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 que cela fonctionne la première fois, à chaque fois. Demandez à de nouvelles personnes d'essayer de mettre en œuvre votre API de temps en temps pour vérifier que cela ne vous dérange pas d'une manière ou d'une autre.
Rester simple. Ne faites aucune authentification sophistiquée. Ne faites pas de schéma d'URL personnalisé fou. Ne réinventez pas SOAP, JSON, REST ou quoi que ce soit. Utilisez tous les outils que vous pouvez qui ont déjà été mis en œuvre et qui 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 à une langue pour s'interfacer avec votre service. Il existe de bons outils pour générer automatiquement une bibliothèque pour vous, tels que Alpaga 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 une API open source, ou s'il existe un processus d'inscription de quelque sorte que ce soit, 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 intervention 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 suivis de bogues et l'assistance par e-mail sont des débuts fantastiques, mais assurez-vous que lorsque quelqu'un publie un bogue, vous le corrigez vraiment. Personne ne veut voir un forum de ville fantôme ou une liste géante de bogues qui n'ont pas été résolus.
Les services Web et leurs API abondent. Malheureusement, la grande majorité sont difficiles à utiliser. Les raisons vont de la mauvaise conception, au manque de documentation, à la volatilité, aux 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. Ces API sont vraiment rares et sont donc beaucoup plus susceptibles d'être largement adoptées et utilisées.
En relation: Un tutoriel pour le reverse engineering de l'API privée de votre logiciel: pirater votre canapé
