Uma das melhores partes do meu trabalho é trabalhar com empresas em sua estratégia de API. Você aprende muito sobre eles dessa maneira. Abrir serviços com uma API é mais que um projeto de engenharia. Para a maioria, é uma nova maneira de pensar sobre seus negócios.

E tendo visto esses projetos de perto, posso dizer que certas abordagens para APIs funcionam, e outras funcionam, digamos, menos.

Mesmo desenvolvedores experientes tendem a ter uma mentalidade de curto prazo ao criar APIs. Geralmente é assim. Eles trabalham para trás a partir do aplicativo para chegar à especificação. Eles iniciam um turbilhão de codificação, verificam as caixas de recursos e funcionalidade e trazem o projeto, esperançosamente no prazo e dentro do orçamento. Bem feito e fora do pub, certo?

Não é bem assim.

O que poderia dar errado?

Isto não é Campo dos sonhos. Só porque você constrói uma API, isso não significa que alguém a usará. Se você não está projetando sua API para encantar seus consumidores, neste caso, sua comunidade de desenvolvedores e até mesmo sua própria equipe, está se preparando para o fracasso. É tão verdadeiro com uma API quanto com um smartphone.

Os projetos de API de maior sucesso usam o que eu chamo de “desenho em primeiro lugar” abordagem. Fundamentalmente, design-first é sobre criar uma experiência que encanta seu público. Antes de escrever qualquer código, pense nas pessoas que usarão sua API. Pergunte a si mesmo: “Estou criando uma experiência que irá atrair uma comunidade, inspirar o engajamento e fornecer valor?” Acima de tudo, “Eu gostaria de desenvolver com essa API?”

Veja como ter certeza de que você pode responder sim a essas perguntas.

Design para consistência

Planejar muito pouco é perigoso. Mas também está planejando demais. Este não é um experimento científico para encontrar o design ideal. A perfeição não é o objetivo: a consistência é.

Faça um favor a seus usuários e estabeleça padrões bem definidos e elementos de design comuns que você usará de novo e de novo à medida que seu aplicativo evoluir. Se você tem duas equipes criando duas APIs para o seu software, os usuários não conseguirão detectar nenhuma diferença.

A segurança deve se comportar da mesma maneira. O controle de versão, os esquemas de URL, as chaves de API e os códigos de erro devem ter a mesma aparência e funcionar em todas as partes de sua API. O mesmo vale para consultar e receber dados. Estes podem parecer o básico, mas eles são tão raramente seguidos na prática - e tão poderosos quando são. Planejar sua API com uma linguagem de modelagem como RAML pode ajudá-lo a manter as melhores práticas.

Se você precisar de outro incentivo para ser consistente, lembre-se de que também está fazendo um favor a si mesmo. Todo o trabalho que você está fazendo em sua API agora, você fará novamente algum dia. Talvez no momento em que você esteja criando um aplicativo para dispositivos móveis nativo. Com o tempo, você desejará adicionar recursos. Você pode querer suportar diferentes plataformas. Quando você faz isso, a última coisa que você quer é gastar tempo reestruturando sua API. Um design claro e consistente servirá a você em boa posição durante a vida útil de sua aplicação.

Design para escala

Sua API precisa ser construída para durar, mas planejar o crescimento pode ser complicado. Você não pode investir muito em escalabilidade até gerar o tráfego. Mas você precisa investir o suficiente para crescer sem afetar seus usuários. É um equilíbrio delicado.

A solução mais fácil é publicar suas APIs em uma plataforma de nuvem, na qual a escalabilidade é incorporada. Dessa forma, se você obter picos de atividade, seu serviço não desmoronará sob a carga.

Você também precisa escolher sua plataforma de gerenciamento de API com cuidado. Não pode ser uma reflexão tardia. É uma ferramenta poderosa para garantir que todos os seus usuários tenham uma boa experiência. Ele permite que você prescreva detalhadamente como sua API será acessada. Ele fornece uma experiência segura e protegida para usuários finais e fornece visibilidade de como a API está sendo acessada. É o Controle da Missão da sua API, e você não pode negligenciá-lo.

Design para pessoas


Dito tudo isso, os desenvolvedores são o fator mais importante que determina o sucesso ou o fracasso de uma API. Não importa o quão elegante seja o seu código, não será suficiente para que as pessoas se envolvam.

As pessoas não querem pensar muito. As práticas de design de software podem ficar envolvidas no atoleiro dos casos de borda; a ladainha de coisas possíveis que um desenvolvedor aleatório poderia fazer um dia. Defina o que você pode fazer com a API e o que você não pode; Deixe a pia da cozinha na cozinha. O processo de design deve direcionar o foco. É melhor começar a estreitar e ampliar ao longo do tempo. Também é essencial definir explicitamente os limites da sua API v1.0 para que os desenvolvedores tenham um contexto do que esperar.

Você precisa pensar na experiência de engajamento da sua API. Após o lançamento, você precisa ajudar os desenvolvedores a descobrir sua API e obter sucesso com ela por meio de documentação e tutoriais. Você precisa promovê-lo, coletar feedback, envolver a comunidade para melhorá-lo. Uma API precisa evoluir, assim como os negócios que ela suporta.

Quer alguns bons exemplos? Tome uma sugestão de empresas como Stripe e Twilio, onde sua API é o produto. Se eles não atraem uma comunidade, seus negócios vão abaixo. Você pode apostar que eles estão recebendo o noivado certo.

Em suma

Criar uma estratégia de API forte é uma experiência estimulante e estimulante. Obriga você a pensar não apenas em como sua aplicação é agora, mas no que será no futuro. Se você mantiver seu foco na experiência do usuário por meio de um bom design inicial e de planejamento a longo prazo, você terá uma arquitetura que pode dar suporte ao seu negócio digital nos próximos anos..

  • Ross Mason é fundador e vice-presidente de estratégia de produtos da MuleSoft.