Quais são os princípios básicos de um bom design de API?

Em uma excelente palestra proferida no Google em 2007, o engenheiro de software e autor técnico, Joshua Bloch, afirma que as APIs são um recurso de negócios extremamente importante. Isso ocorre principalmente porque, se a API for exposta aos clientes, eles poderão optar por investir pesadamente nela, dificultando a transição.

Por outro lado, diz Bloch, “APIs mal projetadas podem causar um fluxo interminável de chamadas de suporte, tornando extremamente difícil para uma empresa progredir”.

Bloch, que liderou o design e a implementação de vários recursos da plataforma Java, incluindo o Java Collections Framework, ressalta ainda que “pensar em termos de design de API tende a melhorar a qualidade dos programas que você escreve”.

Mesmo que, como programador, você não trabalhe em uma API pública, você ainda cria APIs o tempo todo. Uma boa programação é modular e os limites entre módulos são APIs. Da mesma forma, se você trabalhar em um sistema moderno e distribuído do tipo microsserviços, os limites do serviço serão novamente APIs, embora arquitetados de maneira um pouco diferente.

No entanto, o design de API é uma área com a qual muitos programadores parecem ter dificuldades. Então, quais são as características de uma boa?

Nomes são críticos

Em um nível elevado, a API deve ser fácil de aprender e escrever, e difícil de usar indevidamente. Sua API também precisará evoluir, e um bom design leva isso em conta.

A maneira como você nomeia as coisas é realmente importante, já que uma API é, na verdade, uma pequena linguagem que seus usuários precisam aprender.

“Nomes realmente bons contornam problemas e evitam mal-entendidos porque o nome certo deixa muito claro o que algo é”, disse Harry Richardson, cientista-chefe da SoftIron, ao The New Stack.

Richardson chamou a atenção para o fato de que, para os desenvolvedores, os nomes moldam nosso modelo mental.

“É muito trabalhoso voltar atrás e mudar um modelo mental, não necessariamente em termos de código, mas em termos de como você pensa sobre as coisas.”

Em vista disso, realmente vale a pena dedicar algum tempo para encontrar um nome que transmita com muita precisão o que uma determinada API faz.

As ferramentas padrão de um escritor – um dicionário e um enciclopédia – podem ser úteis. Se você encontrar algo particularmente difícil de nomear, isso pode indicar que ele está tentando fazer muitas coisas ao mesmo tempo. Por mais que uma frase excessivamente complexa precise ser dividida em duas, esteja preparado para dividir um módulo excessivamente complexo, se necessário.

Evite abreviações enigmáticas que não fazem sentido e tome cuidado com a falta de consistência, como usar várias palavras que significam a mesma coisa. Por exemplo, se você precisar devolver o salário base de determinado funcionário, evite criar dois métodos, como getBasicSalary() e getBaseSalary() — Se sua API tiver um remove() método e um delete() método, você saberia a diferença, ou mesmo se existe?

A linguagem usada deve ser internamente consistente com quaisquer outras APIs expostas pela organização ou fornecedor. Esta necessidade de consistência significa que pode ser útil ter um certo grau de governação centralizada.

Algumas empresas maiores, por exemplo, ampliarão a função de redator técnico sênior para ajudar as equipes de engenharia com a nomenclatura consistente de métodos, atributos e campos.

Se você estiver trabalhando com um sistema estilo REST, Daniel Bryant, consultor independente e coautor do livro O’Reilly “Mastering API Architecture” sugere examinar um conjunto pré-existente de diretrizes de API, pois elas podem ajudá-lo com consistência no comportamento da API. Para uma API baseada em HTTP, OpenAPI é uma que ele recomenda considerar, e há outras, incluindo Atlassian, Google e Microsoft.

Também vale a pena dizer que, embora todas as APIs precisem de nomes apropriados, os nomes em si são específicos do domínio; uma API escrita para um quant, por exemplo, usaria uma linguagem muito diferente de uma API escrita para um varejista. Idealmente, os termos escolhidos devem corresponder àqueles que a empresa já utiliza e, pelo menos, compreende.

Para garantir isso, Bryant disse ao The New Stack que é melhor realizar pesquisas com usuários e certificar-se de cobrir todos os grupos que podem usar a API.

“O pessoal do controle de qualidade terá ideias diferentes sobre como sua API deve funcionar em comparação com como os desenvolvedores a veriam”, disse ele. “Muitas vezes vi desenvolvedores projetarem uma API sem perguntar quem iria usá-la e acabando expondo o modelo de domínio interno.”

Ele recomenda pensar em termos de “Tarefas a serem realizadas”, como em: Qual é a sua tarefa principal? Qual é o seu fluxo de trabalho? Como você aborda isso? Como você gostaria de abordar isso? A última questão é fundamental, uma vez que a inércia pode acumular-se em torno de processos bem estabelecidos.

“Você pode abalar o mundo das pessoas se puder simplificar as coisas, e geralmente há boas oportunidades quando os sistemas evoluíram ao longo do tempo”, disse Bryant.

O Princípio da Menor Surpresa

Sua API também deve ser idiomática em relação à linguagem de programação na qual foi escrita e respeitar a maneira como essa linguagem funciona. Por exemplo, se a API for usada com Java, use exceções para erros, em vez de retornar um código de erro como faria em C.

As APIs devem seguir o princípio da menor surpresa. Parte da forma como isto pode ser alcançado é através da simetria; se você precisar adicionar e remover métodos, eles deverão ser aplicados em todos os lugares onde forem apropriados.

Uma boa API compreende um pequeno número de conceitos; se estou aprendendo, não deveria ter que aprender muitas coisas. Isso não se aplica necessariamente ao número de métodos, classes ou parâmetros, mas sim à área de superfície conceitual que a API cobre. Idealmente, uma API deve ter como objetivo apenas uma coisa.

Também é melhor evitar adicionar qualquer coisa só por adicionar. “Na dúvida, deixe de fora”, como diz Bloch. Geralmente, você pode adicionar algo a uma API se for necessário, mas nunca poderá remover coisas quando uma API se tornar pública.

Conforme observado anteriormente, sua API precisará evoluir com o tempo, portanto, uma parte importante do design é ser capaz de fazer alterações posteriormente sem destruir tudo.

“Em última análise, a chave para isso é que a API reflita a realidade”, disse Richardson. “Então, por exemplo, se uma pessoa pode ter mais de um endereço ou número de telefone, mesmo que você só se importe com um no momento, permitir apenas um endereço não é realidade. E ignorar a realidade sempre irá te morder.”

APIs são para sempre

Um antipadrão comum, de acordo com Richardson, é implementar uma API parcial porque essa é a única peça que você precisa no momento. O perigo aqui é que você não pense bem na API e acabe com algo que não funciona em outros casos.

“Você precisa pensar mais no design da API do que em qualquer outra coisa”, disse Richardson, “porque você não pode alterá-lo depois de construído”.

Uma segunda questão diz respeito ao encapsulamento e ao vazamento de detalhes de implementação.

“Se um detalhe de implementação vazar, você não poderá alterá-lo”, disse Richardson. “Então você precisa pensar: que operações estão acontecendo aqui? Do que se trata realmente a estrutura de dados?”

Normalmente, o tratamento de erros é um local que passa despercebido. Se você estiver usando um banco de dados como armazenamento de back-end, por exemplo, não deixe que um erro SQL se propague, porque se você quiser alterar o mecanismo de armazenamento posteriormente, não poderá.

Assim como qualquer outro aspecto do desenvolvimento de software, é um erro imaginar que você pode se trancar em uma sala e trabalhar isoladamente na API. Se você fizer isso, você corre o risco de investir demais em seu design, mesmo quando ele dá errado. É muito melhor testar suas ideias frequentemente com as partes interessadas, assim como faria com qualquer outro sistema.

Antes de começar a codificar uma API, é uma boa ideia escrever uma breve especificação que você possa mostrar às partes interessadas, detalhando o que ela faz e como funcionará. Manter as especificações curtas aumenta a probabilidade de sua leitura e evita que você invista demais em sua solução antecipadamente. Se você passou meses escrevendo uma especificação de 100 páginas, é muito menos provável que admita que ela não é boa.

A documentação é uma das facetas mais subvalorizadas, não apenas no design de APIs, mas na computação em geral. Os redatores técnicos são frequentemente subvalorizados e mal pagos, e a documentação é tratada, na melhor das hipóteses, como uma reflexão tardia, exemplificada pela máxima “o código é a documentação”. Isso é um absurdo perigoso.

Embora você queira que sua API seja fácil de entender e aprender, a documentação dela ainda é extremamente importante. Deve ser completo e abrangente e, no mínimo, cobrir cada método, o que cada campo faz e quais são as condições de erro.

“Você deseja listar todos os códigos de erro possíveis que podem ser retornados e em que circunstâncias”, enfatizou Richardson.

Reserve um tempo para refinar e revisar a documentação e evite problemas comuns, como o uso de siglas que não serão facilmente compreendidas.

Continue a escrever código em sua API à medida que você o desenvolve. Bloch observa que os desenvolvedores geralmente param no meio do processo, mas continuar escrevendo na API durante a implementação dá a você uma noção real de quando e como ela funciona.

“Esse código não é desperdiçado”, observa Bloch, “já que ajuda a produzir um produto melhor e também fornece um conjunto de exemplos com os quais outros programadores podem aprender”.

Esses exemplos são críticos porque serão copiados repetidamente por outros desenvolvedores e influenciarão fundamentalmente a forma como uma API é usada.

A postagem Quais são os princípios básicos de um bom design de API? apareceu primeiro em The New Stack.