Compartilhar:
){kind=small}
Alyssa is a writer and editor specializing in technology and the software development space. She lives in central California with her husband, kids, and three rescue dogs.
Desenvolvimento orientado pela OpenAPI na Nexmo
Tempo de leitura: 4 minutos
Na Nexmo, adotamos um processo de desenvolvimento baseado na OpenAPI. Veja por quê.
A história nos ensinou que o desenvolvimento de software fica paralisado sob o peso de especificações excessivamente detalhadas.
Andy Hunt, coautor do Manifesto Ágil, conta a história de um projeto no qual trabalhou na década de 1990. Após dois anos e meio e vários milhões de dólares, o arquiteto do projeto havia produzido uma sala cheia de diagramas UML, mas nem uma única linha de código havia sido implantada.
Hoje, equilibramos cuidadosamente a necessidade de especificações iniciais com a compreensão de que, muitas vezes, é somente ao escrever o próprio código que descobrimos a verdadeira natureza do problema que estamos resolvendo.
No entanto, verifica-se que o equilíbrio entre especificações e descoberta é diferente para APIs públicas do que quando estamos desenvolvendo outros tipos de software. E na Nexmo, isso nos levou a mudar a forma como desenvolvemos novas APIs: a primeira coisa que fazemos ao desenvolver um novo serviço é criar uma especificação OpenAPI. Isso nos traz benefícios em termos de experiência do desenvolvedor, legibilidade para humanos em comparação com máquinas, automação e muito mais.
As APIs são contratos públicos. Quando criamos e lançamos algo como nossa Messages API, estamos fazendo um acordo com nossos clientes: se você fizer a chamada X à API com os dados Y, nossa plataforma fará Z.
Isso faz com que a criação de uma API pública seja, essencialmente, o mesmo que criar um padrão. Pense no SVG. É um padrão para gráficos vetoriais. O padrão e as diversas implementações desse padrão existem como coisas distintas. Se eu escrever uma biblioteca que gera arquivos SVG, não devo me preocupar com os detalhes de implementação do software que, posteriormente, irá ler esse arquivo.
Com muita frequência, as APIs são moldadas pela implementação subjacente — o que Joel Spolsky chama de “abstrações com vazamentos”— ou por decisões de projeto tomadas na hora. Começar criando uma especificação OpenAPI significa que podemos tomar decisões de projeto intencionais, um passo à frente dos detalhes do que está acontecendo nos bastidores. Por sua vez, isso leva a uma experiência consistente e intuitiva para o desenvolvedor.
Um benefício inesperado é que a criação de especificações OpenAPI revela possíveis problemas de usabilidade. Descobrimos que, se for difícil modelar uma API em uma especificação OpenAPI, isso geralmente significa que a própria API será difícil de usar. Isso nos levou a repensar alguns projetos de API que não eram ideais e que, de outra forma, poderiam ter chegado à produção.
Taylor Barnett, da Stoplight.io, descreve as especificações da OpenAPI como “um contrato de desenvolvimento, uma ponte entre equipes”. Embora sejam os seres humanos que escrevem o código, as APIs atuam explicitamente como interfaces entre máquinas.
O desenvolvimento orientado pela especificação OpenAPI transforma a API em muito mais do que apenas uma interface entre dois trechos de código. Ele transforma a API em uma fonte de consenso entre as pessoas. Os redatores técnicos podem usá-la para dar início aos trabalhos de documentação; os defensores dos desenvolvedores, para explicá-la a desenvolvedores externos; e os gerentes de produto, para mantê-la como fonte de referência quanto aos recursos da API.
Conforme documentado por Kin Lane, as empresas estão cada vez mais publicando suas especificações OpenAPI no GitHub como uma declaração pública sobre o projeto de uma API. Com um único documento, podemos criar uma declaração legível tanto por máquinas quanto por pessoas sobre como a API deve se comportar. A partir daí, os desenvolvedores podem ver qual é o comportamento esperado e avaliar os recursos da API.
As especificações da OpenAPI prometem possibilitar todos os tipos de automação. O potencial reside na capacidade de gerar automaticamente bibliotecas de clientes, endpoints simulados, testes e documentação.
Screenshot of API
Na Nexmo, estamos no início dessa jornada. Atualmente, estamos gerando automaticamente documentação de referência da API e alguns testes. Em particular, percebemos que ter uma especificação OpenAPI disponível desde o início facilitou a criação de testes básicos.
Nossas especificações OpenAPI definem as entradas e saídas esperadas da API, incluindo mensagens de erro. Podemos usar essa especificação para gerar automaticamente testes de verificação básica que fornecem dados intencionalmente incorretos e, em seguida, verificam se a mensagem de erro esperada é retornada.
Em última análise, a maior vantagem de todas é que, ao começarmos com uma especificação OpenAPI, temos uma única fonte de referência. Em vez de termos projetos de API em formatos diferentes e em locais distintos (wikis, Google Docs etc.), a especificação agora é simplesmente uma parte padrão do processo de desenvolvimento e é criada com o uso de ferramentas padrão de desenvolvimento.
Essa única especificação é uma forma de informarmos a nós mesmos e aos nossos colegas quando o desenvolvimento estiver concluído e de dizer aos desenvolvedores externos o que esperar. De certa forma, a especificação é a API, e a implementação é apenas isso.
Estamos no início de nossa jornada com a abordagem “OpenAPI-first”. Até o momento, testamos o processo com duas APIs —Redact e Secret Management—, mas todas as nossas APIs possuem especificações OpenAPI completas e públicas, e planejamos migrar todo o nosso desenvolvimento para o modelo “spec-first”.
Com base no trabalho que realizamos até agora, temos certeza de que isso resultará em implementações de API de maior qualidade, economia de tempo e uma compreensão mais profunda. Estamos ansiosos para ver como isso irá melhorar a qualidade das APIs em todo o setor.