Les spécifications qui nous définissent

En tant que développeur, je suis paresseux. Si quelqu'un a créé un logiciel qui résout un problème que je rencontre, je veux l'utiliser. Je devrais être en mesure de me mettre au travail et de me familiariser rapidement avec une nouvelle bibliothèque sans trop d'interférences.

En tant que chef d'initiative de l'équipe SDK serveur de Nexmo, l'un de mes objectifs a été de m'assurer que nous fournissions la meilleure expérience possible aux développeurs qui utilisent nos SDK. Quel est l'intérêt d'un SDK si son utilisation est aussi pénible que de fouiller dans la documentation et de faire des requêtes HTTP brutes ? Notre équipe veut s'assurer que vous puissiez faire votre travail de création de logiciels plus rapidement.

Récemment, l'équipe s'est réunie et a décidé d'examiner les spécifications existantes du SDK serveur (anciennement appelées spécifications du SDK client) pour voir si elles tenaient la route. Les spécifications ont été rédigées en 2016, lorsque Nexmo a commencé à réfléchir de manière plus critique à la façon dont nous écrivons nos logiciels. En 2020, nous avons maintenant six SDK de langues différentes, chaque langue ayant ses propres particularités. Que devons-nous faire différemment aujourd'hui qu'il y a quelques années ?

Moins de RFC, plus de flexibilité

La première chose à faire a été de supprimer une grande partie du langage inspiré des RFC. Le raisonnement était assez simple : les RFC fournissent une structure et un verbiage connus qui ont fait l'objet d'un accord. Grâce à la RFC 2119des mots comme MUST, MUST NOT, SHOULD, SHOULD NOTet d'autres ont tous leur propre définition et définissent les attentes quant à la manière dont les RFC seront rédigés. Si quelqu'un créait un nouveau document de spécification, ces mots auraient un sens total.

Quatre ans et cinq autres SDK plus tard, le document était devenu assez strict en ce qui concerne non seulement les fonctionnalités, mais aussi la mise en œuvre directe. Il détaillait non seulement le comportement, mais aussi la manière dont les clients de l'API devaient être structurés. Cela a provoqué une scission naturelle dans la manière dont certains SDK ont été conçus et a forcé d'autres SDK à faire les choses d'une manière qui n'était pas très naturelle du point de vue de la langue. Un SDK Ruby doit-il ressembler et agir comme une bibliothèque NodeJS ?

Probablement pas.

Nous avons donc supprimé une grande partie du langage relatif aux constructions linguistiques spécifiques, mais nous avons conservé les objectifs généraux et les buts des différentes idées. les objectifs généraux et les buts des différentes idées qui, selon nous, rendent un SDK facile à utiliser. Les erreurs et exceptions suivent toujours l'idée qu'une bibliothèque doit lancer des exceptions explicites de serveur ou de réponse, tandis que les instructions concernant le nommage des choses ont été réduites à "voici une liste de verbes que vous devriez utiliser" La spécification ne dicte plus d'invocations directes de méthodes mais suggère un nommage cohérent.

La spécification s'intéresse beaucoup moins à l'homogénéité des SDK qu'à l'adéquation des attentes et des meilleures pratiques des langues. Au fil du temps, cela signifie que nos API SDK publiques changeront, mais qu'elles évolueront vers ce que vous attendez en tant que développeur du langage X. Nous voulons que les SDK fournissent une expérience que vous obtiendriez avec n'importe quelle bibliothèque bien construite de votre langage.

Abstraction de l'aspect HTTP

Ce qui est génial avec Nexmo, c'est que tout le monde peut immédiatement commencer à utiliser notre API en tapant simplement une adresse web. L'internet a permis d'interagir rapidement avec des machines à travers le monde en utilisant un protocole standard, HTTP, et une interface textuelle simple à travers JSON et XML. Nous pouvons relier différents services comme jamais auparavant.

Mais pourquoi, lorsque vous devez utiliser la synthèse vocale lors d'un appel, devons-nous vous demander de faire un $talk->put()? D'un point de vue sémantique, cela n'a aucun sens.

Oui, Nexmo fournit une API géniale, mais lorsque vous créez votre logiciel, vous ne devriez pas vraiment vous soucier de ce que nous sommes. Si vous souhaitez utiliser la synthèse vocale lors d'un appel, Nexmo est beaucoup plus clair sur ses intentions, $call->playTextToSpeech("Hello World") est beaucoup plus clair dans ses intentions. Cela peut faire une requête HTTP PUT pour effectuer le travail, mais il n'y a pas de raison de nommer nos méthodes comme des méthodes HTTP.

Nous avons nettoyé les verbes et conventions d'appellation à une liste d'actions que vous entreprendriez pour faire votre travail, et non pour écrire un client HTTP. Les développeurs utilisent les SDK pour faire abstraction des services tiers qu'ils utilisent, et nous devrions donc contribuer à maintenir cette abstraction avec nos conventions de nommage. En fin de compte, personne ne se soucie de savoir si nous avons utilisé un PUT ou a POST pour faire quelque chose, ils veulent juste trouver et effectuer une action.

La commodité avant tout

Je veux m'assurer que non seulement nos SDK fournissent toutes les différentes façons d'interagir avec notre plateforme, mais aussi que l'interface est facile à comprendre et à utiliser. Nos SDK doivent vous aider à résoudre vos problèmes en étant explicites sur le travail effectué tout en vous aidant à vous occuper de la paperasserie qui peut accompagner ce travail.

Si nous revenons à notre exemple d'intégration de la synthèse vocale dans un appel existant, notre méthode actuelle est un peu obtuse du point de vue de la clarté et de la sémantique. Trouver comment faire quelque chose dans notre SDK devrait être explicite, mais aussi rapide. Je ne veux pas qu'un développeur revienne à son code dans six mois et essaie de comprendre pourquoi talk() renvoie un objet au lieu d'effectuer une action. Je veux que le développeur puisse facilement lire son propre code et savoir exactement ce qui se passe à tout moment.

// Current, pull a Talk object out of a specific call
$talk = $client->calls['abcd-123']->talk();
// Set the text
$talk->setText(TEXT);
// PUT the text back to the API
$talk->put();

// In the future, we will just find a specific call
$call = $client->calls()->find('abcd-123');
// And play Text to Speech into it
$call->playTextToSpeech("All your base are belong to us");

L'avenir

L'équipe SDK Serveur est actuellement en train de passer en revue tous nos SDK principaux (NodeJS, Java, Python, .NET, Rubyet PHP) et de les confronter à la nouvelle spécification. Nous avons des changements passionnants à venir car nous nous concentrons sur l'expérience des développeurs avec nos SDK, et nous voulons fournir à tous nos clients la même facilité d'utilisation qu'ils ont toujours attendue de nos SDK d'une manière plus moderne et plus propre.

Comme toujours, nous apprécions les commentaires de nos clients. Nous construisons ce logiciel pour vous faciliter la vie. Si vous nous voyez lors d'une conférence ou d'un meetingup, faites-nous savoir comment nous nous débrouillons ! Y a-t-il quelque chose que vous aimeriez voir dans nos SDK ? N'hésitez pas à nous contacter sur Github et faites-nous savoir s'il y a des fonctionnalités qui vous manquent.