As revisões de design de API estão mortas. Viva as análises de design de API!

Jul 28, 2023

Artigos da página inicial do InfoQ As análises de design de API estão mortas. Viva as análises de design de API!

22 de maio de 2023 8 minutos de leitura

por

Jason Harmon

revisados ​​pela

Thomas Betts

Ao projetar APIs em escala, é necessário um esforço deliberado para criar consistência. A principal diferença entre um monte de APIs e algo que parece uma verdadeira plataforma é a consistência. Nesse caso, consistência significa simplesmente que, se você usar várias APIs, fatores como convenções de nomenclatura, padrões de interação como paginação e mecanismos de autenticação serão padrão em todos os aspectos.

Tradicionalmente, os comitês de revisão traumatizam os desenvolvedores de APIs com descobertas que induzem atrasos quando o desenvolvimento é considerado concluído. Pior ainda, o design por comitê pode assumir o controle, paralisando o progresso ou incentivando os desenvolvedores a encontrar maneiras de contornar o processo para evitar totalmente o sofrimento.

Para desbloquear verdadeiramente uma plataforma moderna, a capacitação através da governação descentralizada é uma abordagem muito mais escalável e envolvente. Isso significa simplesmente que cada domínio ou área funcional tem um especialista no assunto que foi treinado nos padrões e na arquitetura geral para ser um guia bem capacitado para desenvolvedores de API.

Proteja identidades. Serviços digitais seguros. Permita o acesso de usuário escalonável e seguro a aplicativos da Web e móveis. Comece o teste gratuito.

Mais importante ainda, chegar a um acordo sobre o design da API antes que a maior parte do desenvolvimento esteja concluída pode evitar, em grande parte, descobertas de última hora que colocam em risco os prazos de entrega (muitas vezes referida como uma abordagem de design primeiro). Usar um formato de especificação como OpenAPI (o padrão de fato para APIs HTTP/"REST") fornece a capacidade de definir uma API antes de qualquer desenvolvimento, o que permite alinhamento e identificação de problemas muito mais cedo.

Com esse contexto em mente, vamos examinar mais de perto como conduzir revisões de design de API e como desenvolver processos e preparar a organização para evitar prazos prolongados e falta de envolvimento do desenvolvedor.

Aqui estão alguns pré-requisitos importantes para garantir um processo tranquilo:

O uso de APIs é uma experiência muito destilada e, como tal, o impacto da linguagem é desproporcionalmente maior do que a maioria dos outros domínios de design. Cada membro da equipe pode ter uma maneira ligeiramente diferente de definir e descrever vários termos, o que se manifesta em confusão e diminuição da produtividade das equipes de API.

Embora os portais/documentação de API sejam essenciais para uma ótima experiência do desenvolvedor, APIs bem projetadas devem contar a maior parte da história sem ter que pensar muito sobre isso. Se os termos forem familiares ao consumidor e os padrões de interação forem óbvios, a experiência poderá ser rápida e indolor. Consistência é a principal diferença de experiência entre um monte de APIs e algo que parece uma plataforma.

Ao estabelecer seu programa de API e processo de governança, comece com uma linguagem compartilhada. Embora possa parecer impossível no início, definir um vocabulário/gramática compartilhado centrado no cliente para sua plataforma é essencial e um acelerador geral para uma organização. Muitos termos podem ter significados variados dentro de uma empresa e, para piorar as coisas, muitas vezes são termos que os consumidores finais nem sequer reconheceriam.

Fazer esse dever de casa antecipadamente evita conflitos sobre nomenclatura durante o projeto de APIs. Trabalhe em cada domínio com as partes interessadas relevantes para definir a terminologia compartilhada e garantir ampla disponibilidade e conscientização aos designers de API. E depois de definir a padronização interna dos termos, não se esqueça de verificar se ela também atende às suas necessidades externas. Usar a linguagem do cliente e ter uma visão centrada no cliente do desenvolvimento de API ajuda as equipes a evitar confundir seus clientes com termos técnicos desconhecidos, portanto, garanta que haja sincronização entre seu entendimento interno e externo.