O que é design de APIs?

O design de APIs é o processo de criação de interfaces de programação de aplicações (APIs) que expõem dados e funcionalidades de aplicação para a utilização de desenvolvedores e usuários. As APIs são importantes para as empresas modernas pois proporcionam novos recursos para todas as áreas, de operações e produtos a estratégias de parceria. Podemos dizer que hoje, a maioria das empresas já nem pergunta se deve participar de programas de APIs, mas como fazê-lo.

Um programa de APIs eficaz baseia-se na estratégia institucional da empresa, contribuindo para alcançar seus objetivos. Você saberá que tem uma ótima estratégia quando conseguir responder às três perguntas a seguir com clareza:

1. Por que queremos implementar APIs?
2. Que resultados tangíveis queremos alcançar com essas APIs?
3. Como planejamos executar o programa de APIs para alcançar esses resultados?

Por que

Essa pergunta costuma ser interpretada incorretamente pelas pessoas de diferentes maneiras. Primeiramente, em vez de se concentrar no valor da própria API, é bom pensar no valor gerado por ela. Lembre-se de que o valor vem dos principais negócios da organização, e não necessariamente da API. Ela é valiosa quando se torna um canal que fornece novos tipos de acesso ao valor agregado existente de uma organização.

Outro equívoco comum é acreditar que para uma API ser valiosa, seus usuários precisam estivar dispostos a pagar por ela. Isso só será verdade se a API for o próprio produto. Na maioria dos modelos, esse não é o caso. Geralmente, as APIs impulsionam outras métricas, como vendas, clientes afiliados, percepção de marca etc. O valor da API percebido pelos usuários é o resultado de uma solicitação de serviço e sua resposta (API call), e não a chamada em si.

De acordo com uma pesquisa com a participação de 152 organizações realizada pela Cutter Consortium e Wipro, os objetivos de negócios mais comuns quando as empresas decidem criar um programa de APIs são: desenvolver novas parcerias, aumentar a receita, explorar novos modelos de negócios, acelerar o time to market e estabelecer novos canais de distribuição. Os principais objetivos tecnológicos são aprimorar a integração de aplicações e de recursos mobile e oferecer suporte à conexão com mais dispositivos. Os benefícios precisam ser sólidos o suficiente para que o investimento em APIs seja uma escolha óbvia para a empresa.

O quê

A segunda pergunta é "Que resultados tangíveis queremos alcançar com as APIs?". Em outras palavras, "O que as APIs realmente fazem e como elas afetam a estratégia geral de negócios?".

Tanto o ponto de vista vista interno quanto o ponto de vista externo de uma empresa ajudam a definir o funcionamento das APIs. O ponto de vista interno se refere aos ativos uma organização. Quanto mais valiosos e exclusivos forem os serviços e recursos oferecidos, mais o programa de APIs será indicado para eles.

Uma organização que possui informações exclusivas pode oferecer acesso a elas via API. Conteúdos, dados e serviços podem tornar uma API muito valiosa.

Antes de definir o que uma API deve trazer para a empresa, é necessário examinar ambos
os pontos de vista. A decisão final costuma ser uma combinação deles.

Resumindo, embora seja improvável que o "por quê" mude com frequência, o "o quê" pode variar muito de acordo com fatores externos como mercados, considerações técnicas ou condições econômicas. O direcionamento interno sobre o valor de um ativo também pode mudar e acabar afetando o que se pretende alcançar com uma API.

Como

A última pergunta, "Como projetamos o nosso programa de APIs para alcançar os resultados desejados?", refere-se à implementação e execução.

As equipes precisam se perguntar:

• Que tecnologia será usada para criar as APIs?
• Como as APIs serão projetadas?
• Como será a manutenção das APIs?
• Como as APIs serão divulgadas dentro e fora da empresa?
• Quais os recursos disponíveis?
• Quem precisa estar na equipe?
• Como monitoraremos o sucesso com base nos objetivos de negócios?

Uma equipe de API é parecida com uma equipe de "produto". Sejam seus clientes internos ou externos, você é responsável por criar, implantar, operar e otimizar a infraestrutura que eles usam.

Assim como as equipes de produto, as equipes de API também são muito diversificadas. Elas costumam incluir um responsável pela solução que atua como guardião da estratégia e das metas, uma equipe de design focada em assegurar que as melhores práticas sejam aplicadas ao projeto, engenheiros que desenvolvem a tecnologia e funcionários operacionais que a executam a API.

Ao longo do tempo, você pode incluir mais pessoas, como membros das equipes de suporte e comunidades, evangelistas, agentes de segurança e muitos outros.

Como John Musser destacou em sua palestra na convenção O’Reilly Open Source de 2012, para que uma API seja ótima ela precisa:

1. Fornecer um serviço valioso
2. Ter um plano e um modelo de negócios
3. Ser simples, flexível e fácil de adotar
4. Ser gerenciada e mensurada
5. Oferecer um excelente suporte aos desenvolvedores

Oferecer um serviço valioso é especialmente importante na hora de pensar no porquê de ter um programa de APIs. A proposta de valor é o principal fator para o sucesso de uma API. Se a proposta de valor de uma API estiver incorreta ou não existir, será muito difícil – talvez impossível – encontrar usuários para ela.

Praticamente qualquer empresa que tenha um produto, seja ele digital ou física, pode agregar valor
por meio de uma API se ela estiver vinculada a ofertas existentes e for capaz de aprimorá-las. Para agregar valor, basta que a API esteja estruturada para abranger casos de uso relevantes para os desenvolvedores.

Encontrar o valor da sua API e descrevê-lo é um processo rotineiro. A primeira etapa é descrever as tarefas que seus usuários querem executar. Alguns exemplos:

• Enviar mensagens urgentes automaticamente aos membros da equipe durante uma emergência
• Fazer o backup de arquivos críticos para garantir que eles nunca sejam perdidos
• Coletar amostras de dados para detectar determinados eventos

A próxima etapa é identificar os desafios específicos que afetam os usuários antes, durante e depois da realização de uma tarefa:

• Assegurar a confiabilidade do envio com várias tentativas, detectar falhas, preocupar-se com o envio de várias mensagens em vez de apenas uma e integrar-se a diferentes sistemas de entrega de mensagens dependendo da localização do usuário
• Assegurar a entrega segura dos arquivos, diminuindo o volume de largura de banda utilizado na transferência
• Processar enormes quantidades de dados e tentar correlacioná-los em tempo real

A terceira etapa é listar os possíveis benefícios para os usuários:

• Enviar outros tipos de notificações que criem oportunidades em vez de apenas alertas de possíveis ameaças
• Livrar-se de outros equipamentos de armazenamento se a confiabilidade atender às suas necessidades
• Ativar ações automaticamente com base em eventos

Ao avaliar essas questões, pense de maneira abrangente e liste tudo o que os usuários poderão utilizar, como suporte, documentação e portais do desenvolvedor. Em seguida, defina como você pretende eliminar ou reduzir alguns dos incômodos que surgem antes, durante ou depois dos usuários executarem uma tarefa. Isso também inclui os problemas que podem impedi-los de realizá-la. Depois, descreva como pretende criar benefícios para os usuários da sua API.

Ao aplicar esse processo aos nossos três exemplos acima, podemos obter:

• Uma API de mensageria multicanal com entrega de mensagens em uma única chamada e a habilidade de realizar novas tentativas automaticamente até que a entrega seja assegurada (por exemplo, Twilio e PagerDuty)
• Uma API de sincronização de armazenamento com chamadas otimizadas para verificar com eficiência se as novas versões precisam ser sincronizadas (por exemplo, Bitcasa e Box)
• Uma API para agregar diversas fontes de dados em um fluxo configurável que pode ser filtrado, extraído e facilmente gerenciado (por exemplo, GNIP e DataSift)

Por fim, um ótimo exercício é compor criar afirmações que demonstrem a relação da API com o perfil do usuário. Se você tiver dificuldades para identificar essas afirmações, será necessário reconsiderar o modelo da API. Talvez você precise adicionar, revisar, redefinir ou remover funcionalidades da API. Ou então, a sua API oferece um excelente valor, mas você está tentando abordar os usuários errados.

Quando você conseguir consolida e resumir todas as suas afirmações em uma única frase, terá definido a proposta de valor da sua APIs. No caso da API de mensageria acima, a proposta de valor seria mais ou menos assim:

Nossa API de mensageria oferece aos desenvolvedores corporativos uma funcionalidade de mensagens de texto confiável, com garantia e sem latência para aplicações empresariais críticas. A API também conta com o suporte de kits de desenvolvimento de software (SDKs) que abrangem a maioria das linguagens de programação para uma integração mais rápida.

Em alguns casos, pode parecer muito trabalho para criar apenas uma API interna. No entanto, é essencial manter o foco no valor, inclusive nos casos de uso internos. Uma proposta de valor mal elaborada torna o processo de demonstrar o mérito da API para outras equipes mais difícil. Uma proposta de valor bem definida facilita a adoção do programa de APIs e o torna uma grande contribuição para o negócio.

Para definir o valor do seu programa de APIs, considere estas cinco perguntas:

1. Quem é o usuário? Para responder, leve em consideração a relação dos usuários com você (são clientes atuais, parceiros ou desenvolvedores externos?), a função que eles desempenham (são cientistas de dados, desenvolvedores mobile ou funcionários operacionais?) e seus requisitos e preferências.
2. Que problemas do usuário estamos resolvendo e/ou que benefícios vamos gerar para ele? Considere os negócios do cliente, os desafios e os ganhos definidos na proposta de valor, se alguma necessidade crítica está sendo atendida (é um problema ou oportunidade de gerar lucros?) e que métricas serão aprimoradas (velocidade, receita, economia de custo ou implantação de inovações).
3. Sua API funciona para quais casos de uso? Identifique, com a ajuda da proposta de valor, as soluções para os desafios dos usuários ou as oportunidades geradas pela API mais eficazes para sua empresa e para o usuário. Planeje a API para lidar com esses casos de uso.
4. Como o valor para usuário será ampliado ao longo do tempo? Elabore a proposta de valor considerando mudanças futuras. Quais são os seus principais marcos de projeto futuros relacionados a mudanças externas e internas?
5. Qual é o valor gerado internamente para a sua organização? Considere os benefícios internos e como a API pode ser valiosa para os negócios.

Definir o valor da API é um passo importante no design do seu programa. No entanto, as APIs também geram custo, e isso precisa ser equilibrado pelo valor. Embora não possa ser medido em termos monetários, o valor precisa ser real. Por exemplo:

• Qual é o negócio central da empresa no momento?
• Como a API pode ser usada para acelerar ou aumentar esse negócio?

Em alguns casos, as APIs podem gerar oportunidades corporativas totalmente novas, fora do modelo de negócios atual da organização. Mesmo nesses casos, as APIs geralmente usam ativos ou experiência já existentes para criar novas oportunidades.

Em resumo, há três motivos por que determinar o modelo de negócios correto é importante para criar programas de APIs eficazes:

1. Isso coloca em foco o valor da API para a organização, o que orienta decisões relacionadas a compromissos a longo prazo com o programa da API. Sem esses compromissos, raramente haverá recursos para concluir as tarefas necessárias para estabelecer e executar um programa de APIs eficaz.
2. Isso ajuda a definir a funcionalidade da solução, algo necessário para atender a terceiros e gerar negócios.
3. Isso garante que seja dada a devida atenção aos papéis e responsabilidades dentro organização e a quem retém que partes do valor gerado pela API. Além de definir o que os usuários da API ganham com seu uso e como esse ganho é equilibrado em relação aos ganhos do provedor da API.

Um bom design de API segue alguns princípios básicos, que podem ser implementados de formas diferentes. Por exemplo, pense nesta analogia: todos os carros têm volante, pedal de freio e acelerador. As luzes de alerta, a abertura automática do porta-malas e o rádio são um pouco diferentes de acordo com o modelo. Ainda assim, é raro ver um motorista experiente que não saiba dirigir um carro alugado.

Esse nível de design "pronto para uso" é o que grandes equipes de API sempre buscam. Ou seja, APIs que exigem pouca ou nenhuma explicação para serem usadas pela primeira vez por profissionais experientes.

Simplicidade

A simplicidade do design da API depende do contexto. Um determinado design pode ser simples em um caso de uso, mas muito complexo em outro. Por isso, é necessário equilibrar o nível de detalhes dos métodos de API. É bom pensar na simplicidade em vários níveis, incluindo:

• Formato dos dados Suporte a XML, JSON, formatos proprietários ou uma combinação dessas opções.
• Estrutura dos métodos Os métodos podem ser muito genéricos, retornando um amplo conjunto de dados, ou bastante específicos para permitir solicitações segmentadas. Eles geralmente são chamados em uma determinada sequência para alcançar certos casos de uso.
• Modelo de dados O modelo de dados subjacente pode ser muito parecido com o que realmente é exposto por meio da API ou bastante diferente disso. Isso afeta a usabilidade e de manutenção.
• Autenticação Mecanismos de autenticação distintos têm pontos fortes e fracos diferentes. A opção mais adequada depende do contexto.
• Políticas de uso Precisa ser fácil entender e trabalhar com os direitos e as cotas dos desenvolvedores.

Não é fácil criar APIs que sejam ao mesmo tempo simples e flexíveis. Uma API criada levando em conta somente a simplicidade corre o risco de ser excessivamente personalizada e servir apenas para casos de uso muito específicos, não sendo flexível o suficiente para outros casos.

Para criar flexibilidade, primeiro descubra qual o seu potencial ambiente de operações, incluindo os modelos de dados e sistemas subjacentes. Defina qual subconjunto dessas operações é viável e valioso. Para encontrar o melhor equilíbrio entre simplicidade e flexibilidade:

• Exponhaoperações atômicas: ao combinar operações atômicas, é possível cobrir todo o espaço
• Identifique os casos de uso mais comuns e valiosos Para atender a esses casos de uso, projete uma segunda camada de metaoperações que combine diversas operações atômicas.

Sem dúvida, o conceito de hipermídia como plataforma de estado da aplicação (HATEOAS) pode trazer ainda mais flexibilidade porque possibilita mudanças de ambiente de execução em operações de cliente e na API. Para aumentar a flexibilidade, o HATEOAS facilita a documentação e o controle de versões. No entanto, no design da API, é necessário considerar diversas questões.

Para planejar o design da API, considere as cinco perguntas a seguir:

1. Projetamos a API para oferecer suporte aos nossos casos de uso? Depois de identificar os principais casos de uso, é necessário projetar a API para que ela ofereça suporte a eles. É importante ter flexibilidade para não excluir os casos de uso que podem ser menos frequentes, mas que ainda precisam de suporte para possibilitar a inovação.
2. Temos motivo para usar uma API RESTful?As APIs RESTful estão na moda, mas você não deve seguir essa tendência apenas por isso. Elas se aplicam muito bem a alguns casos de uso, mas há outras APIs que favorecem diferentes estilos de arquitetura, como a GraphQL.
3. Estamos expondo nosso modelo de dados sem pensar nos casos de uso? A API precisa ter o suporte de uma camada que faça abstrações a partir do modelo de dados real. Como regra geral, não crie uma API que vá diretamente ao banco de dados (embora haja casos em que isso seja necessário).
4. Quais as regiões geográficas mais importantes? Planejamos nossos datacenters de acordo com elas?O design da API também precisa abranger elementos não funcionais, como latência e disponibilidade. Escolha datacenters que tenham uma localização geográfica próxima de onde a maioria dos usuários está.
5. Estamos sincronizando o design da API com nossas outras soluções? Se a API não for a única solução da sua empresa, garanta que o design dela seja consistente com o das suas outras soluções. Mas também pode ser que você decida criar um design totalmente do das API das outras soluções. Se esse for o caso, os planos precisam ser bem definidos e relatados interna e externamente.

Uma métrica importante para aprimorar o design da API e garantir sua fácil adoção é o "Time to First Hello World" (TTFHW). Em outras palavras, quanto tempo o desenvolvedor precisa para alcançar uma solução minimamente viável com sua API? Essa é uma ótima maneira de se colocar no lugar de um desenvolvedor que quer testar sua API para ver o que é necessário para que algo funcione.

Quando você definir o início e o término da métrica TTFHW, recomendamos abordar a maior quantidade possível de aspectos do engajamento do desenvolvedor. Depois, otimize essas informações para melhorar a rapidez e conveniência.

Poder passar pelo processo rapidamente também cria no desenvolvedor a confiança de que a API é bem organizada e que provavelmente tudo funcionará como esperado. Quando você demora muito para garantir esse "momento de sucesso", corre o risco de perder desenvolvedores.

Além do TTFHW, recomendamos outra métrica: Time to First Profitable App (TTFPA). Ela é mais complexo, porque "lucrativo" ("profitable", no nome da métrica) é apenas uma questão de definição e depende da sua API e estratégia de negócios. Veja isso como algo útil, porque leva você a pensar sobre os aspectos relacionados às operações da API como parte do seu programa.

Os dois princípios básicos da experiência do desenvolvedor são:

1. A solução ou serviço deve fornecer um valor claro aos desenvolvedores e atenda a desafios ou oportunidades definidos. Isso pode ser um valor monetário ou outro valor, como uma maneira de aumentar o alcance, a divulgação da marca, a base de clientes, as vendas indiretas, a reputação do desenvolvedor ou apenas a vontade de usar uma tecnologia excelente e que realmente funciona.
2. A solução precisa ser acessada facilmente. Isso inclui ter um mecanismo leve de registro (ou nenhum), acesso a recursos de teste, excelente documentação e uma grande quantidade de código-fonte limpo e gratuito.

Sugerimos que a maioria dos programas de API tenha um programa para desenvolvedores, seja qual for a exposição das APIs: pública, somente para parceiros ou apenas interna. As provisões podem ser mais ou menos elaboradas dependendo do público.

Portal do desenvolvedor

O principal elemento do programa de desenvolvedores é esse portal. Ele é o principal ponto de entrada para eles se inscreverem nas suas APIs, acessá-las e usá-las. O acesso dos desenvolvedores à API precisa ser simples e fácil. Eles devem começar o mais rápido possível.

A melhor métrica para avaliar isso é o TTFHW. Pense também em otimizar o processo de inscrição: quanto mais simples e mais rápido, melhor. Uma prática recomendada é dar aos desenvolvedores a oportunidade de invocar as APIs para examinar o funcionamento delas (solicitação e resposta) sem precisar de nenhum processo de inscrição. Além disso, para diminuir a curva de aprendizado, há ótimas opções de conteúdo complementar, como guias de introdução, documentação de referência da API e código-fonte.

Aceleração por meio de ecossistema de parceiros

Como provedor de API, você atua em um ecossistema de parceiros e fornecedores. Esses parceiros costumam ter os próprios meios e redes de comunicação e de distribuição de conteúdo. Recomendamos que você identifique parceiros, pois isso pode ser útil para aumentar a adoção da sua API. Muitas vezes, eles são descobertos quando as APIs são complementares e agregam valor aos desenvolvedores quando combinadas.

Questões a serem consideradas para avaliar a experiência do desenvolvedor:

1. Como explicamos o valor da API logo de cara? Desenvolva uma descrição bem resumida da proposta de valor da API que seja adequado aos desenvolvedores.
2. Quais são os nossos TTFHW e TTFPA e como reduzi-los? Pensar no TTFHW completo é uma maneira eficiente de tornar sua API mais fácil de usar para o desenvolvedor. Recomendamos que você pense nas métricas de TTFHW e TTFPA ao considerar quaisquer elementos adicionados à experiência do desenvolvedor (como portais) e todos os aspectos alteráveis da API.
3. Como é o processo de integração dos desenvolvedores? Ele é o mais simples possível? Este processo precisar estar alinhado aos casos de uso da API. Naturalmente, o nível de segurança precisa ser maior no acesso a dados e APIs mais confidenciais, o que provavelmente requer contratos mais formais. O restante precisa ser muito simples e direto para garantir o sucesso rápido do desenvolvedor (TTFHW).
4. Estamos sendo flexíveis o suficiente para que a API seja atrativa para os desenvolvedores? É ótimo que você tenha encontrado a proposta de valor certa e os desenvolvedores estejam se inscrevendo na sua API. Lembre-se de que ajudá-los a garantir o sucesso os tornará usuários fiéis e trará mais usuários.
5. Como oferecemos suporte aos desenvolvedores se eles tiverem problemas? Acreditamos na abordagem de autosserviço, que ajuda você a escalar. Muitas dúvidas dos desenvolvedores podem ser resolvidas com uma ótima documentação, perguntas frequentes ou fóruns. No entanto, o autosserviço tem seus limites. Para as dúvidas mais aprofundadas ou outras complicações como, por exemplo, problemas no faturamento, é necessário fornecer algum tipo de mecanismo de suporte.
6. Nossa documentação oferece suporte à inovação? Que tipo de suporte oferecemos a desenvolvedores que participam de casos de uso incomuns ou desejam fazer algo novo? Boas ideias podem surgir de qualquer lugar.