5 étapes pour créer une API réussie

C'est la nature du développement logiciel. Les développeurs créent des logiciels en pensant à l'utilisateur final. Cela semble assez simple, mais parfois ces utilisateurs sont également des collègues développeurs. Ils n'ont pas besoin de choses en panne pour eux. Ils n'ont même pas besoin de simplicité. Tout ce qu'ils veulent, c'est un accès - un moyen d'intégrer votre logiciel au leur. C'est là qu'intervient une API (interface de programmation d'application). J'espère mettre en évidence cinq étapes que vous pouvez suivre pour créer une API réussie.

Fais tes devoirs

En matière de développement logiciel, aucun de nous ne veut réinventer la roue. À ce stade, presque toutes les grandes entreprises Web ont des API pour leurs produits logiciels. Étudiez ces API et essayez de reprendre les différentes décisions de conception qui ont contribué à leur création.

Il existe de nombreuses technologies différentes, mais la plupart des API que vous verrez utiliseront soit une interface RESTful, soit SOAP. Si vous ne savez pas quelle interface API vous allez utiliser, je vous suggère d'utiliser une approche RESTful en utilisant le protocole HTTP. Il est plus simple que SOAP, il est actuellement plus populaire et il sera plus facile de commencer avec un produit logiciel basé sur le Web.

Être cohérent

L'une des choses que les développeurs apprécient le plus est la cohérence. Cela inclut, entre autres, l'adressabilité, les arguments d'entrée, les formats de sortie et la gestion des erreurs.

Lorsque vous utilisez une approche RESTful, il existe de nombreux schémas de dénomination URI différents. Chacun a ses partisans, alors choisissez-en un et respectez-le. Il en va de même avec la structure d'entrée et de sortie. La plupart des API prennent en charge l'utilisation de XML et JSON comme formats d'entrée et de sortie. Je suggère de prendre en charge les deux, mais de choisir un format par défaut.

Pour l'entrée, vos exigences d'entrée doivent être nommées de manière cohérente et doivent avoir un sens dans le contexte de l'appel d'API que vous effectuez. Pour la sortie, assurez-vous que vous utilisez des dispositions de structure de données communes. Si vous encapsulez la sortie d'un appel d'API dans un Balise XML, envisagez de le faire avec vos autres appels.

Il est courant d'inclure une sorte d'indicateur d'état dans les données de sortie que vous renvoyez au client. Lorsque vous utilisez une approche API RESTful, cela doit être fait à l'aide de codes d'état HTTP. Par exemple, si vous venez de traiter une demande PUT sur un objet de données existant, le code d'état HTTP que vous incluez dans votre réponse variera en fonction du résultat de la demande.

Au lieu d'un indicateur arbitraire qui indique l'état de l'appel, un code d'état standard "200 OK" peut être utilisé pour indiquer que la demande a abouti, tandis qu'un code d'état "400 Bad Request" peut être utilisé pour indiquer que la demande a été malformé. Il existe de nombreux codes d'état HTTP qui peuvent être utilisés dans différentes situations.

Utilisez OAuth

La plupart des produits logiciels impliquent une sorte d'authentification d'utilisateur afin d'accéder aux ressources protégées pour cet utilisateur. En ce qui concerne les API, demander au client de collecter les informations d'identification de l'utilisateur à envoyer à votre serveur est une mauvaise pratique. C'est là qu'intervient OAuth.

OAuth offre de nombreux avantages par rapport à l'authentification par nom d'utilisateur / mot de passe tiers. Surtout, le client n'a jamais accès aux informations d'identification de l'utilisateur. L'utilisateur est redirigé vers votre serveur lorsqu'il se connecte. Une fois l'utilisateur connecté à votre site, il est redirigé vers le client où le client recevra un jeton d'accès à utiliser lors de futures demandes de ressources protégées.

Un autre avantage important de l'utilisation d'OAuth est la possibilité pour l'utilisateur d'annuler l'accès client à tout moment. Si l'utilisateur décide que, pour une raison quelconque, il ne souhaite plus que le client puisse accéder aux ressources protégées en son nom, il accède simplement à une interface que vous avez créée et annule l'accès du client.

Commencer de bonne heure

L'une des choses les plus importantes que vous puissiez faire pour réussir votre API est de commencer tôt. Lorsque vous écrivez cette fonction pour créer une entrée dans votre base de données, allez-y, prenez le temps supplémentaire et écrivez une interface API pour cela.

Rédiger une bonne documentation

Rien ne tue une API plus rapidement que de ne pas avoir une bonne documentation. Alors que certains développeurs peuvent prendre une API mal documentée et comprendre comment elle est censée fonctionner, la plupart n'en voudront pas.

Vous devez documenter chaque appel d'API dont vous disposez et classer vos appels d'API en fonction du type de données sur lesquelles ils agissent. En plus de documenter les points de terminaison pour les appels API eux-mêmes, vous devez définir systématiquement les arguments d'entrée requis et facultatifs ainsi que les structures de données de sortie. Les arguments d'entrée doivent répertorier une valeur par défaut, le cas échéant, et indiquer également le format de données attendu, tel qu'un nombre ou une chaîne. Enfin, chaque appel d'API doit avoir une liste de conditions d'erreur et de codes d'état.

Pour compléter votre documentation, assurez-vous d'inclure un ou deux exemples de scénarios d'entrée et de sortie courants pour chaque appel d'API.

Développement d'API: Keep It Simple

Bien qu'il puisse sembler que le développement d'une API soit une entreprise compliquée, l'idée d'une API elle-même n'est pas un nouveau concept et il existe une grande quantité de documentation disponible sur chaque sujet que nous avons abordé ici. Assurez-vous simplement d'utiliser les bonnes pratiques là où vous pouvez les trouver et de fournir une interface cohérente et bien documentée.