As especificações que nos definem

Como desenvolvedor, sou preguiçoso. Se alguém já criou um software que resolve um problema que eu tenho, quero usá-lo. Eu deveria poder começar a trabalhar imediatamente e me familiarizar rapidamente com uma nova biblioteca, sem muitas complicações.

Como líder de iniciativa da equipe do SDK para servidores da Nexmo, um dos meus objetivos tem sido garantir que estejamos oferecendo a melhor experiência possível aos desenvolvedores que utilizam nossos SDKs. De que adianta um SDK se usá-lo é tão trabalhoso quanto vasculhar a documentação e fazer solicitações HTTP brutas? Nossa equipe quer garantir que você consiga realizar seu trabalho — a criação de software — mais rapidamente.

Recentemente, a equipe se reuniu e decidiu revisar as especificações existentes do SDK do servidor (anteriormente chamadas de especificações do Client SDK) para verificar se elas ainda estavam atualizadas. As especificações foram elaboradas em 2016, quando a Nexmo começou a refletir de forma mais crítica sobre como desenvolvíamos nosso software. Em 2020, mantemos seis SDKs em diferentes linguagens de programação, cada uma com suas particularidades. O que precisamos fazer de diferente hoje em relação a anos atrás?

Menos RFC, mais flexibilidade

A primeira medida foi eliminar grande parte da linguagem inspirada nos RFCs. O raciocínio era bastante simples: os RFCs oferecem uma estrutura e uma terminologia conhecidas e já acordadas. Graças ao RFC 2119, palavras como MUST, MUST NOT, SHOULD, SHOULD NOT, entre outras, têm suas próprias definições específicas e estabelecem expectativas sobre como as RFCs devem ser redigidas. Se alguém estivesse criando um novo documento de especificação, essas palavras fariam todo o sentido.

Quatro anos e mais cinco SDKs depois, o documento havia se tornado bastante rigoroso não apenas em relação à funcionalidade, mas também à implementação direta. Ele detalhava não apenas o comportamento, mas também como os clientes da API deveriam ser estruturados. Isso causou uma divisão natural na forma como alguns SDKs foram projetados e forçou outros SDKs a fazer as coisas de uma maneira que não era muito natural para a linguagem. Um SDK para Ruby deveria se parecer e funcionar como uma biblioteca do NodeJS?

Provavelmente não.

Portanto, removemos grande parte do conteúdo relacionado a construções específicas da linguagem, mas mantivemos os objetivos e metas gerais das várias ideias que, em nossa opinião, tornam um SDK fácil de usar. Erros e exceções ainda seguem a ideia de que uma biblioteca deve lançar exceções explícitas do tipo `Server` ou `Response`, enquanto as orientações sobre nomenclatura foram reduzidas a “aqui está uma lista de verbos que você deve usar”. A especificação não determina mais a invocação direta de métodos, mas sugere uma nomenclatura consistente.

A especificação está muito menos interessada em tornar os SDKs uma experiência homogênea e agora promove uma diretriz de alinhamento com as expectativas da linguagem e as melhores práticas. Com o tempo, isso significa que nossas APIs públicas dos SDKs passarão a mudar, mas mudarão para algo que você, como desenvolvedor da Linguagem X, espera. Queremos que os SDKs ofereçam a mesma experiência que você teria com qualquer biblioteca bem construída da sua linguagem.

Abstrair o aspecto HTTP

O que é incrível no Nexmo é que qualquer pessoa pode começar a usar nossa API imediatamente, bastando acessar um endereço da web. A internet ajudou a tornar possível interagir rapidamente com máquinas em todo o mundo usando um protocolo padrão, o HTTP, e uma interface textual simples por meio de JSON e XML. Podemos conectar vários serviços entre si como nunca antes.

Mas por que, quando você precisa reproduzir a leitura de texto em voz alta durante uma ligação, estamos pedindo que você faça um $talk->put()? Semanticamente, isso não faz sentido.

Sim, a Nexmo oferece uma API incrível, mas, ao criar seu software, você não deveria se preocupar com quem somos. Se você quiser reproduzir um texto com sintetizador de voz durante uma chamada, $call->playTextToSpeech("Hello World") fica muito mais claro em relação às suas intenções. Isso pode exigir uma solicitação HTTP PUT para realizar a tarefa, mas não há motivo para nomearmos nossos métodos com base nos métodos HTTP.

Nós organizamos os verbos e as convenções de nomenclatura para uma lista de ações que você realizaria para concluir um trabalho, e não para escrever um cliente HTTP. Os desenvolvedores usam SDKs para abstrair os serviços de terceiros que utilizam; portanto, devemos ajudar a manter essa abstração com nossas convenções de nomenclatura. No fim das contas, ninguém se importa se usamos um PUT ou um POST para fazer algo; eles só querem encontrar e executar uma ação.

A conveniência acima de tudo

Quero garantir que nossos SDKs não apenas ofereçam todas as diferentes formas de interagir com nossa plataforma, mas também que a interface seja fácil de entender e de usar. Nossos SDKs devem ajudar você a resolver seu problema, sendo claros sobre o trabalho que está sendo realizado e, ao mesmo tempo, ajudando a lidar com as tarefas rotineiras que podem surgir durante o trabalho.

Se voltarmos ao nosso exemplo de reproduzir texto-para-voz em uma chamada já em andamento, nossa abordagem atual é um pouco confusa do ponto de vista da clareza e da semântica. Descobrir como fazer algo em nosso SDK deve ser explícito, mas também rápido de se fazer. Não quero que um desenvolvedor volte ao seu código daqui a seis meses e tente descobrir por que talk() retorna um objeto em vez de executar uma ação. Quero que o desenvolvedor leia facilmente seu próprio código e saiba exatamente o que está acontecendo a todo momento.

// 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");

O Futuro

A equipe do Server SDK está, no momento, analisando todos os nossos SDKs da linha principal (NodeJS, Java, Python, .NET, Rubye PHP) e analisando-as à luz da nova especificação. Temos algumas mudanças empolgantes por vir, à medida que nos concentramos na experiência do desenvolvedor com nossos SDKs, e queremos oferecer a todos os nossos clientes a mesma facilidade de uso que eles sempre esperaram de nossos SDKs, de uma forma mais moderna e simples.

Como sempre, adoramos receber feedback de nossos clientes. Desenvolvemos este software para facilitar a vida de vocês. Se nos encontrarem em uma conferência ou em um encontro, contem-nos o que acham do nosso trabalho! Há algo que vocês gostariam de ver em nossos SDKs? Entrem em contato conosco no GitHub e nos diga se há algum recurso que você acha que está faltando.