Get best of the week

Guia de Estilo da API ou não faça os usuários pensarem



Olá! Meu nome é Lesha Rutskoi e sou gerente de produtos da Wrike. Antes disso, ele trabalhou na Adform e PandaDoc. Nos últimos cinco anos, tenho feito tudo relacionado a integrações e APIs.

Wrike é um produto de colaboração e gerenciamento de projetos SaaS. Queremos que os desenvolvedores construam suas soluções com base no Wrike e, para isso, precisamos que nossa API seja conveniente. Ao mesmo tempo, temos 9 escritórios em todo o mundo, e 3 deles são escritórios de desenvolvimento. É bastante difícil criar uma API consistente usando equipes distribuídas que falam idiomas diferentes. Há uma probabilidade crescente de que suas decisões comecem a se contradizer. Nesse caso, não se pode prescindir de um conjunto uniforme de regras para todos.

Se você também trabalha de maneira distribuída e cria sua própria API, a API do Style Guide pode ajudá-lo. Quero lhe dizer quais problemas comuns ele resolve e como facilita a vida dos desenvolvedores. Também compartilharei minha experiência escrevendo e implementando meu próprio Guia de Estilo de API na empresa.

Por que precisamos de uma API conveniente?


Muitos leitores provavelmente tiveram que resolver problemas usando a API não tão conveniente. Sim, isso não é muito simples e leva mais tempo, mas geralmente você ainda pode resolver o problema.

Então, por que perder tempo e esforço da equipe para melhorar a API? A resposta é bastante simples: muitas vezes a decisão sobre o uso do seu produto é tomada pelos desenvolvedores, especialmente quando se trata de APIs e integrações. Portanto, é importante pensar não apenas na experiência do usuário (UX), mas também na experiência do desenvolvedor do DX.

Vou dar um exemplo. Certa vez, trabalhei em uma equipe responsável por toda a integração do produto. Muitas vezes, no meio do trimestre, quando nossos planos já estavam delineados, um profissional de marketing chegava e dizia: “O Z criou um novo mercado e lançará a próxima versão de sua plataforma. Em breve, eles terão um evento público interessante, onde podemos conversar sobre nossa integração e sucesso! Será ótimo se escrevermos rapidamente essa integração agora. ” O que fizemos neste caso? Se um desenvolvedor experiente em uma equipe conseguir fazer o protótipo de trabalho mínimo em três dias, na maioria das vezes em duas ou três semanas, conseguimos levar a tarefa à perfeição. Se faltavam alguns dias, a API e a documentação eram mais ou menos.Não fazia sentido redesenhar planos e empreender uma nova integração - mesmo assim, nada valeria a pena até a data de vencimento. Lembre-se de que seu produto pode estar nessa situação - os parceiros decidirão lidar com você, dependendo da rapidez e conveniência de começar a trabalhar com sua API.

Mas quase ninguém quer criar uma API ruim. Por que todo mundo fica diferente? Normalmente, uma API se desenvolve assim. Quando uma startup começa a crescer e os primeiros clientes chegam a ela, uma das equipes cria seu ponto de extremidade e decide transferir a versão para o URL:

imagem

Gradualmente, novos clientes e novas necessidades aparecem. Os caras da segunda equipe estão incluídos no trabalho, que acreditam que é melhor usar seus próprios tipos de mídia para a versão:

imagem

Depois de um tempo, a terceira equipe chega. Em uma conferência, eles descobrem que o Stripe está versionando sua API com as principais datas de lançamento. E eles decidem fazer o mesmo:

imagem

O resultado é uma API na qual existem três métodos de versão. Todos os métodos funcionam, mas funcionam de maneira diferente.

Como desenvolvedor, seria inconveniente para mim usar essa API. E o motivo não é que prefiro uma abordagem de versionamento a todos os outros. Apenas usar vários métodos ao mesmo tempo é inconveniente. Você precisará escrever o código três vezes que funcione com a API ou usar três bibliotecas diferentes. E isso significa que haverá três vezes mais erros.

E há datas e horários. Mesmo usando a abordagem padrão, os dados podem ser transmitidos de diferentes maneiras: pelo fuso horário do seu servidor, pelo GMT, pelo horário no cliente, no horário do Unix. Os clientes precisarão trazer todos os dados para um formato.

As mensagens de erro geralmente fazem tudo de maneira diferente. Por exemplo, assim:

imagem

Ou assim:

imagem

Também há minha mensagem de erro favorita - uma resposta vazia:

imagem

Bem, apenas um clássico - a resposta é 200 OK, dentro da qual está o JSON com uma descrição do que deu errado.

Na minha opinião, o mais importante em uma boa API é a consistência . Não importa qual abordagem de versão você escolher, o principal é que seja a mesma em toda a API. Uma solução ainda mais bem-sucedida seria adotar a abordagem popular que outras empresas já estão adotando. Provavelmente, seus clientes já o encontraram e possuem código ou biblioteca pronta. Não há necessidade de pensar novamente, você pode usar ferramentas prontas.

Uma abordagem única para criar uma API é especialmente importante para grandes empresas com equipes distribuídas. Se dez pessoas na sala criarem uma startup, cada desenvolvedor poderá simplesmente bater no ombro de um vizinho e concordar ou ver os principais problemas durante a revisão do código. Em uma grande empresa, fica mais difícil.

A API do Style Guide ajudará a resolver esses problemas. Este é um documento que descreve os princípios de design da sua API. Se todo mundo usa as mesmas abordagens, parece que a API foi desenvolvida por uma pessoa, e não por muitas equipes diferentes. Essa abordagem é muito parecida com o Code Style Guide, quando as equipes concordam em como escrevem o código. Uma pessoa de uma equipe pode olhar para a base de código de outra equipe e entender rapidamente o que está acontecendo lá.

Como criar seu próprio Guia de Estilo da API?


Arnauld Lauret (conhecido como API Handyman ) criou um site interessante - API Stylebook . Ele montou um Guia de Estilo acessível ao público, que várias empresas (Cisco, Google, Red Hat, agências governamentais e muitas outras) colocam em domínio público.

As diretrizes são divididas em tópicos no site. Por exemplo, se você estiver interessado em controle de versão, na guia Controle de versão, poderá descobrir como diferentes empresas resolvem esse problema.

Aprenda com a experiência de outras pessoas! Mas copiar completamente o Guia de estilo de outra pessoa não é uma boa ideia. Ainda assim, ele resolve os problemas de outra empresa, não a sua.

No seu Guia de estilo, você deve adicionar tópicos próximos à sua empresa e resolver seus problemas. Talvez você tenha muitos aplicativos móveis, e o tamanho da resposta é importante para você. Em seguida, descreva os princípios associados a esse aspecto. Ou você concordou com as equipes internas que era hora de ver o monólito em microsserviços que se comunicariam através do Message Broker. Nesse caso, é necessário incluir os princípios segundo os quais você usará o Kafka ou alguma outra ferramenta no Guia de estilos da API.

O que mais incluir na API do Style Guide


Além disso, o Guia de estilo deve incluir os valores básicos e as abordagens de engenharia às quais a empresa adere.

O que eles podem ser?

  • Write APIs in English. , . - , , . Style Guide, , .
  • API First principle. API : , , frontend-. , API . , , .
  • Use REST e JSON. Isso pode ser importante se você desejar que o maior público possível use sua API ou plataforma. Apesar do fato do GraphQL se tornar cada vez mais popular desde 2017, nem todo mundo sabe disso. A maioria dos desenvolvedores, provavelmente, nunca o usou, o que significa que eles aumentarão o tempo de imersão e desenvolvimento. Por que criar complexidade?

Além disso, os princípios básicos podem ser definidos em tópicos. Por exemplo, dentro do princípio de usar REST e JSON, você pode determinar facilmente quais tópicos devem ser descritos no Guia:

  • Preferir API REST com cargas JSON
    • Solicitações HTTP
    • Códigos de status HTTP
    • Json

Mais sobre cada tópico, você pode criar as regras que todas as equipes da empresa devem seguir:

  • Solicitações HTTP
    • DEVE usar métodos HTTP corretamente
    • HTTP personalizado cabeçalhos devem seguir a convenção de nomenclatura

Eu realmente gosto da abordagem que descreve a necessidade de seguir as regras através dos verbos DEVE, DEVE ou PODE (emprestada da RFC 2119 ). Todo mundo que ler o Guia de estilo fará a distinção entre regras e recomendações obrigatórias.

Veja como, por exemplo, ele aparece em Zalando :

imagem

Itens a serem lembrados ao iniciar o Guia de estilo


  • . , . , , . , , . API management , . API.
  • . - 15- . rate limiting, .. — , , - .
  • . , OAuth, REST. , , , scopes .
  • . , , .
  • . , . , . . . , .
  • . , , .
  • . , , .. : , «user», , «user», .
  • . , — . , (OpenAPI-, -) . .

API Style Guide?


Você criou seu Guia de Estilo da API e agora resta implementá-lo. Isso também não é fácil. Compartilharei minha experiência de implementação do Guia de Estilo da API em um dos locais onde trabalhei. A empresa tinha uma estrutura complexa: centenas de engenheiros, dezenas de equipes distribuídas em quatro escritórios de desenvolvimento, colegas falavam idiomas diferentes.

Primeiro você precisa convencer as partes interessadas. E aqui frequentemente falamos sobre líderes técnicos em vários campos e representantes de negócios. Todos devem entender quais problemas queremos resolver e como o Guia de Estilo pode ajudar. No meu exemplo, todas as partes interessadas entenderam que uma boa API é uma vantagem importante. Muitos clientes vieram com essa solicitação e os concorrentes não cochilaram e expandiram ativamente o escopo de oportunidades disponíveis por meio de sua API.

O próximo passo é encontrar uma equipe que faça isso. No meu caso, a empresa já tinha uma equipe separada que suportava uma API externa. Ela entendeu melhor a necessidade de mudança, porque era constantemente confrontada com dificuldades em seu trabalho. Os membros desta equipe tiveram o prazer de participar do projeto.

Como a equipe implementou a API do Style Guide?

  • Ela falou sobre a iniciativa em conferências internas e hackathons para que todos na empresa entendessem o que estava sendo discutido. Isso ajudou a atrair pessoas afins que foram muito úteis nas próximas etapas.
  • Preparou um rascunho do Guia de Estilo, que posteriormente concordou com os campeões da API (sobre eles um pouco mais).
  • Apresentou o projeto às equipes. Os caras foram a cada escritório de desenvolvimento e conversaram com quase todas as equipes, explicaram o significado do projeto e realizaram treinamentos.
  • Ajudou com o design da API. Era difícil para muitas equipes fazer tudo o que estava na guia pela primeira vez. Ajuda e explicações adicionais foram úteis aqui, especialmente em situações incomuns.
  • Conduziu uma revisão. Era importante verificar se todas as equipes agem de acordo com o Guia de Estilo.

É muito difícil para uma equipe de uma grande empresa implementar essas mudanças significativas. Precisa de suporte. Aqui, os campeões de API estavam conectados - arquitetos e técnicos de cada direção que ajudavam a integrar a ideia em suas equipes e divisões.

Quando ocorrem mudanças importantes, o descontentamento geralmente aparece. Nesse caso, você precisa de uma autoridade que possa convencer essas pessoas da necessidade de mudança. Tehlids são as pessoas mais adequadas para isso.

Os campeões de API em um canal separado do Slack discutiram questões e sugestões emergentes. Pequenas mudanças foram introduzidas imediatamente, enquanto as maiores exigiram uma discussão detalhada. Nesse caso, o iniciador escreveu uma proposta oficial: que problema precisa ser resolvido, que métodos de solução já existem, que vantagens e desvantagens eles têm. Então, por um ou dois dias, nos reunimos fora do escritório, discutimos idéias, escolhemos uma solução e a corrigimos. Depois, contamos às nossas equipes sobre a decisão que tomamos: por que a tomamos e o que precisa ser feito a seguir.

Além disso, os campeões de API ajudaram a fazer revisões em suas áreas. Os caras de suas equipes se voltaram para eles e, em seguida, a revisão final foi conduzida pela equipe que estava criando o Guia de Estilo.

Depois de algum tempo, uma comunidade de API começou a se formar na empresa. Ele incluiu pessoas que passaram por vários ciclos de revisão, descobriram o que é um design bom e correto, por que ele é necessário e como fazê-lo. Criamos um grande bate-papo no qual todos podiam fazer uma pergunta e os membros da comunidade da API ajudaram a resolvê-lo.

Você não pode implementar a abordagem apenas no nível de engenharia. As equipes de vendas, suporte e marketing também devem entender quais cenários de usuário são cobertos pela API, qual o valor que carrega, como se relaciona com a estratégia da empresa e como transmitir adequadamente informações sobre os clientes.

Tentamos introduzir tudo isso na integração da maioria das equipes da empresa, incluindo as que não são de engenharia. Isso também é necessário para que todos entendam quando, em que casos e a quem você pode pedir ajuda.

Automação


O último tópico importante é a automação de processos de rotina. A revisão pode servir como um excelente exemplo. Em uma grande empresa com um grande número de equipes, provavelmente você precisará fazer muitas revisões. Não estou perdendo tempo com problemas básicos, como uma descrição de erro ausente ou um formato de ID incorreto.

Algumas ferramentas podem ajudar com isso:

  • O Zally da Zalando verifica se a especificação OpenAPI corresponde ao seu Guia de estilo da API. A configuração básica do Zally verifica a conformidade com o Zalando Style Guide, mas você pode redefinir e adicionar suas próprias regras.
  • O Dredd do Apiary verifica se a implementação final da API REST corresponde ao seu design, a saber, as especificações OpenAPI, Blueprint ou RAML.

Este artigo é uma transcrição da minha palestra na Miro's Platform Developers Conference . Você pode encontrar o vídeo do discurso aqui .

Ficarei feliz em responder suas perguntas sobre a implementação do Guia de estilo da API. Também será legal se você compartilhar uma experiência semelhante!

Agradecimentos especiais a Daria Ivanova por sua ajuda na preparação deste artigo!

More articles:


All Articles