Écrire soi-même son API et son SDK

N’importe qui ayant fréquenté un hackaton dans sa vie vous le dira, les APIs, c’est génial, ça permet de se brancher sur un service et de l’utiliser pour créer de nouveaux projets (d’ailleurs, pour en savoir plus vous pouvez lire l’article de Damien sur la comsommation d’API en JavaScript). 

Je teste mon niveau technique en quelques minutes! Mais parfois, on se retrouve de l’autre côté de la barrière à devoir écrire soi-même une API ou un SDK pour que d’autres développeurs utilisent notre service. Voici quelques points à garder en tête lorsque l’on doit écrire son API.

API, SDK, Quelle différence?

Avant de plonger dans la question qui nous intéresse, je me permet juste de refaire une distinction entre API et SDK.

Une API est une interface permettant d’interagir avec un service donné. Le plus souvent on parle d’API web, permettant de lire les données d’un service existant, voir d’écrire de nouvelles données sur  ce service. De nos jours, les APIs utilisent souvent des communications standardisées en HTTP, REST, avec des données transitant sous forme de XML ou de JSON. Une API correspond donc à la définition des interactions possible avec un service, et le format des données échangées.

Un SDK et un ensemble d’outils (généralement une librairie compilée) permettant de tirer partie des fonctionnalités d’un service donné. En général, une API peut être utilisée sans SDK mais dans certains cas, il est nécessaire d’utiliser un code spécifique à l’auteur de l’API. Un SDK peut être juste un outil simplifiant la création d’objets à échanger avec le serveur, ou peut effectuer des opérations sensibles ou complexes (décryption de données sécurisées, manipulation de formats de fichiers spéciaux, …).

Ecrire son API  : les trois règles d’or

L’écriture d’une API se fait souvent de manière évolutive. Lorsque le service évolue, en général l’API doit évoluer avec. Tout au long de la conception et de l’écriture de l’API, il est nécessaire de respecter les trois règles d’or suivantes.

Prévoir les erreurs des utilisateurs

Les développeurs qui vont utiliser votre API ne connaisse pas les fonctionnalités, règles et contraintes de votre service par cœur, et n’ont pas forcément le temps de les apprendre non plus. Parfois même leurs connaissances techniques seront très légères. C’est donc votre responsabilité de prendre un maximum d’erreurs en compte. Cela veut dire qu’il faut vérifier que les informations reçues sont valides, même si vous décrivez le format à l’avance dans votre documentation.

En plus de fournir des messages d’erreurs explicites et standardisés (j’ai souvenir d’une API ou les erreurs étaient parfois retournées dans une réponse en XML, et d’autre fois dans le code de retour HTTP… ), il peut être bon de prévoir les erreurs en définissant des valeurs par défaut pour un maximum de paramètres.

Rester consistant

Faites en sorte que les noms de méthodes et de paramètres soient consistants entre eux, et que les structures se ressemblent, afin que l’utilisateur puissent prévoir à quoi ressemblera la méthode qu’il cherche. Cela peut paraître évident, mais lorsqu’une API évolue rapidement, et est maintenue par de multiples développeurs, il arrive que des inconsistances surgissent et troublent les utilisateurs.

Le mieux est d’avoir une nomenclature explicite, et de s’y tenir. Il est d’ailleurs possible d’utiliser un serveur d’intégration continue pour s’en assurer (je vous invite d’ailleurs à lire mon article sur le sujet).

Il est également bon de rester consistant avec des standards existant, ou avec d’autres API avec lesquelles vos utilisateurs pourraient être familiers.

Faciliter la vie des utilisateurs

Lorsque l’on propose une API, publique ou non, c’est que l’on souhaite voir apparaître de nouvelles applications autour de notre service. Plus l’API sera simple à utiliser, plus il y aura d’application. Il est donc nécessaire qu’un utilisateur qui découvre puisse rapidement obtenir un résultat concret. Attention cependant à ne pas faire d’exces et trop simplifier l’API. Il faut qu’un utilisateur avancé ait les moyens de pouvoir faire des actions plus complexes. Il y a donc un dosage à trouver entre simplicité et flexibilité, et malheureusement pas de recette miracle.

Ecrire sa documentation

Ecrire une API et/ou un SDK doit obligatoirement passer par l’écriture de la documentation. Là encore, il faut penser à tous les développeurs qui vont vouloir utiliser votre service. Depuis le développeur amateur qui va avoir besoin de tutoriels clairs et précis, allant à l’essentiel tout en expliquant un minimum les concepts clefs de votre service, à l’expert qui aura besoin de pouvoir accéder rapidement à la documentation précise de chaque point de détail de l’API et du SDK.

Un gros plus dans la documentation est de fournir des exemples pour chaque cas d’utilisation, dans un contexte compréhensible. Encore mieux, vous pouvez fournir une application cliente Open Source sur Github (avec des fichiers commentés), donnant un exemple global et concret. Le principe est de fournir aux utilisateurs un maximum de points d’entrée pour permettre de comprendre, et donc d’utiliser votre service.

Supporter les utilisateurs

Ça y est, votre API est en ligne, vos SDKs téléchargeables, la documentation et les tutoriels sont écrits, et des développeurs commencent à utiliser votre service. Votre tâche ne s’arrete pas là. Il va falloir aider les développeurs qui pourrait rencontrer des problèmes auxquels vous n’avez pas pensé (cela arrive bien plus souvent qu’on le croit).

Pour cela, de nombreuses méthodes existent : fournir une adresse email de support, avoir un forum privé ou les développeurs s’aident entre eux, ou encore suivre les mots clefs liés à votre service sur des sites comme Stack Overflow. Et à chaque problème que rencontre un de vos utilisateurs, pensez à le prendre en compte pour l’évolution de votre API, soit en prévoyant le cas d’utilisation, ou en ajoutant des informations dans la documentation.

Faire évoluer l’API et le SDK

Dans le monde informatique actuelle, tout évolue très vite. Les concurrents, les technologies, plus rien n’est statique. Il faut donc être réactifs pour que votre API et votre SDK restent pertinents.

Garder un œil sur la veille technologique qui vous concerne, pour suivre rapidement les nouveaux standards, ou évaluer l’intérêt de telle ou telle technologie. Pensez également aux développements passés : ne supprimez pas du jour au lendemain une méthode de votre API. Des applications (peut-être anciennes) peuvent encore en dépendre. Prévenez vos utilisateur suffisament à l’avance avant de déprécier une fonctionnalité.

Je teste mon niveau technique en quelques minutes!

Xavier
Geek, Android-ophile, curieux de nature et aimant partager mes connaissances, je baigne dans le monde de la programmation depuis un bon moment, et aujourd’hui je suis principalement porté sur les technologies mobiles, et principalement Android.

J’apprécie autant découvrir de nouvelles techniques, développer des bouts de codes pour générer des images, échanger sur divers sujets techniques, que partager mes connaissances par quelque moyen que ce soit.
Aujourd’hui, je passe mon temps entre Deezer, où je fais partie de l’équipe Android, mes propres applications Android Open Sources, et mes trajets quotidiens en train, entre ma campagne percheronne et Paris.
En savoir +