Notícias

Jul 04, 2023

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

Design de API de artigos da página inicial do InfoQ

Artigos da página inicial do InfoQ As análises de design de API estão mortas. Viva as revisões 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 têm traumatizado os desenvolvedores de API com descobertas indutoras de atraso quando o desenvolvimento é considerado concluído. Pior ainda, o design por comitê pode assumir o controle, paralisando o progresso ou encorajando os desenvolvedores a encontrar maneiras de contornar o processo para evitar completamente a dor.

Para realmente desbloquear uma plataforma moderna, a capacitação por meio de governança 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 educado nos padrões e na arquitetura geral para ser um guia bem capacitado para desenvolvedores de API.

Proteger Identidades. Serviços Digitais Seguros. Habilite o acesso escalonável e seguro do usuário a aplicativos móveis e da Web. Iniciar teste gratuito.

Mais importante, concordar com o design da API antes que a maior parte do desenvolvimento seja concluída pode evitar descobertas de última hora que colocam em risco os prazos de entrega (geralmente chamados de abordagem de design em primeiro lugar). O uso de 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 cronogramas 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 da API sejam essenciais para uma ótima experiência do desenvolvedor, as 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 pode ser rápida e indolor. A consistência é a principal diferença na 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 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 reconheceriam.

Fazer esse dever de casa antecipadamente evita conflitos sobre nomes no meio do design de APIs. Trabalhe em cada domínio com as partes interessadas relevantes para definir a terminologia compartilhada e garantir ampla disponibilidade e conscientização para os 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 da API ajuda as equipes a evitar confundir seus clientes com termos técnicos desconhecidos, portanto, garanta que haja sincronização entre sua compreensão interna e externa.