Os benefícios de uma abordagem API-first para a criação de microsserviços

Andrew Stiefel

As APIs são o tecido conjuntivo das aplicações nativas da nuvem — o meio pelo qual os microsserviços que compõem uma aplicação se comunicam. À medida que as aplicações crescem e ganham escala, o número de microsserviços e APIs também aumenta. Embora esse seja um resultado inevitável na maioria dos casos, ele cria desafios significativos para as equipes de Operações de Plataforma responsáveis por garantir a confiabilidade, a escalabilidade e a segurança das aplicações modernas. Chamamos esse problema de proliferação de APIs e escrevemos sobre ele em uma publicação anterior no blog.

Como primeira tentativa de solucionar a proliferação de APIs, uma organização pode adotar uma abordagem de cima para baixo, implementando ferramentas para a descoberta e a correção automatizadas de APIs. Embora isso seja eficaz no curto prazo, muitas vezes acaba impondo uma carga excessiva às equipes responsáveis por desenvolver e operar APIs e microsserviços. Essas equipes precisam reformular microsserviços e APIs existentes para resolver problemas de segurança e conformidade ou passar por um processo de análise trabalhoso para obter as aprovações necessárias. É por isso que muitas grandes organizações de software adotam uma abordagem descentralizada que usa a governança adaptativa para dar aos desenvolvedores a autonomia de que precisam.

Em vez de implementar medidas de proteção de última hora, uma abordagem de baixo para cima para o problema é mais eficaz a longo prazo. As equipes que desenvolvem e operam APIs para diferentes microsserviços e aplicações são as primeiras a se envolver e, muitas vezes, começam adotando uma abordagem de desenvolvimento de software API-first em sua organização.

O que é API-first?

As APIs existem há décadas. Mas elas não são mais apenas “interfaces de programação de aplicações”. Em sua essência, as APIs são interfaces para desenvolvedores. Como qualquer interface de usuário, as APIs precisam de planejamento, design e testes. A abordagem API-first consiste em reconhecer e priorizar a importância da conectividade e da simplicidade em todas as equipes que operam e utilizam APIs. Ela prioriza a comunicação, a reutilização e a funcionalidade para os consumidores de APIs, que quase sempre são desenvolvedores.

Há muitos caminhos para adotar a abordagem API-first, mas uma abordagem de desenvolvimento de software orientada por design é o objetivo final da maioria das empresas que iniciam uma jornada API-first. Na prática, essa abordagem significa que as APIs são completamente definidas antes da implementação. O trabalho começa com o design e a documentação de como a API funcionará. A equipe se baseia no artefato resultante, muitas vezes chamado de contrato de API, para orientar a implementação das funcionalidades da aplicação.

Conheça técnicas de design para dar suporte a uma abordagem API-first de desenvolvimento de software que seja durável e flexível no Capítulo 1 do e-book Mastering API Architecture da O’Reilly, cortesia da NGINX.

O valor da abordagem API-First para as organizações

Uma estratégia API-first costuma ser ideal para arquiteturas de microsserviços, pois garante que os ecossistemas de aplicações sejam concebidos desde o início como sistemas modulares e reutilizáveis. A adoção de um modelo de desenvolvimento de software API-first oferece benefícios significativos tanto para desenvolvedores quanto para organizações, incluindo:

• Maior produtividade dos desenvolvedores – As equipes de desenvolvimento podem trabalhar em paralelo e atualizar aplicações de back-end sem afetar as equipes que trabalham em outros microsserviços que dependem das APIs dessas aplicações. A colaboração costuma ser mais fácil ao longo do ciclo de vida da API, pois todas as equipes podem consultar o contrato de API estabelecido.
• Experiência aprimorada para desenvolvedores – O design API-first prioriza a experiência do desenvolvedor, garantindo que a API seja lógica e bem documentada. Isso proporciona uma experiência fluida aos desenvolvedores ao interagirem com uma API. Saiba por que é tão importante que as equipes de operações de plataforma levem em consideração a experiência do desenvolvedor com a API<.htmla>.
• Governança e segurança consistentes – Arquitetos de nuvem e de plataforma podem organizar o ecossistema de APIs de forma consistente, incorporando regras de segurança e governança durante a fase de design da API. Isso evita as revisões dispendiosas necessárias quando problemas são descobertos posteriormente no processo de desenvolvimento de software.
• Melhoria da qualidade do software – Projetar as APIs primeiro garante que os requisitos de segurança e conformidade sejam atendidos logo no início do processo de desenvolvimento, muito antes de a API estar pronta para ser implantada em produção. Com menos necessidade de corrigir falhas de segurança em produção, suas equipes de operações, qualidade e engenharia de segurança têm mais tempo para trabalhar diretamente com as equipes de desenvolvimento a fim de garantir que os padrões de qualidade e segurança sejam atendidos na fase de projeto.
• Lançamento mais rápido no mercado – Com menos dependências e uma estrutura consistente para a comunicação entre serviços, diferentes equipes podem criar e aprimorar seus serviços com muito mais eficiência. Uma especificação de API consistente e legível por máquina é uma ferramenta que pode ajudar desenvolvedores e equipes de operações de plataforma a trabalhar melhor em conjunto.

De modo geral, adotar uma abordagem API-first pode ajudar uma empresa a criar uma arquitetura de microsserviços mais flexível, escalável e segura.

Como a adoção de uma especificação comum de API pode ajudar

No cenário típico de microsserviços e APIs empresariais, há mais componentes em operação do que uma equipe de Operações de Plataforma consegue acompanhar diariamente. Adotar uma especificação de API padronizada e legível por máquina ajuda as equipes a entender, monitorar e tomar decisões sobre as APIs que estão em operação em seus ambientes.

Adotar uma especificação de API comum também pode ajudar a melhorar a colaboração com as partes interessadas durante a fase de design da API. Ao criar um contrato de API e formalizá-lo em uma especificação padrão, você garante que todas as partes interessadas estejam alinhadas sobre como a API funcionará. Isso também facilita o compartilhamento de definições e funcionalidades reutilizáveis entre as equipes.

Atualmente, existem três especificações de API comuns, cada uma compatível com a maioria dos tipos de API:

• OpenAPI – descrições em JSON ou YAML de todas as APIs web e webhooks
• AsyncAPI – descrições em JSON ou YAML de APIs orientadas a eventos
• JSON Schema – descrições em JSON dos objetos de esquema usados em APIs

As APIs REST representam a maior parte das APIs em produção atualmente, e a Especificação OpenAPI é a forma padrão de criar uma definição de API para uma API REST. Ela fornece um contrato legível por máquina que descreve como uma determinada API funciona. A Especificação OpenAPI é amplamente compatível com diversas ferramentas de gerenciamento de APIs e gateways de API, incluindo o NGINX. O restante deste blog abordará como você pode usar a Especificação OpenAPI para atender a alguns casos de uso importantes.

A Especificação OpenAPI é um formato de código aberto para definir APIs em JSON ou YAML. É possível incluir uma ampla variedade de características da API, como mostra o exemplo simples de API a seguir. Nele, uma simples requisição HTTP GET retorna uma lista de itens de uma lista de compras fictícia.

openapi: 3.0.0info:
  version: 1.0.0
  title: Grocery List API
  description: An example API to illustrate the OpenAPI Specification

servers:
url: https://api.example.io/v1

paths:
  /list:
    get:
      description: Returns a list of stuff on your grocery list             
      responses:
        '200':
          description: Successfully returned a list
          content:
            schema:
              type: array
              items:
                type: object
                properties:
                   item_name:
                      type: string

As definições que seguem a Especificação OpenAPI podem ser lidas tanto por pessoas quanto por máquinas. Isso significa que há uma única fonte de verdade que documenta o funcionamento de cada API, o que é especialmente importante em organizações com muitas equipes desenvolvendo e operando APIs. Naturalmente, para gerenciar, administrar e proteger APIs em escala, é preciso garantir que as demais ferramentas da sua plataforma de APIs — gateways de API, portais para desenvolvedores e soluções avançadas de segurança — também sejam compatíveis com a Especificação OpenAPI.

Aprofunde-se em como projetar APIs REST usando a Especificação OpenAPI no Capítulo 1 de Mastering API Architecture.

Benefícios da adoção de uma especificação comum de API

Usar uma especificação de API comum, como a Especificação OpenAPI, oferece vários benefícios:

• Interoperabilidade aprimorada – Uma especificação comum e legível por máquina permite que diferentes sistemas e clientes consumam e utilizem o contrato da API. Isso facilita a integração, o gerenciamento e o monitoramento de arquiteturas complexas pelas equipes de Operações de Plataforma.
• Documentação consistente – O contrato da API é documentado em um formato padrão, incluindo os endpoints, os formatos de solicitação e resposta e outros detalhes relevantes. Muitos sistemas podem usar o contrato para gerar uma documentação abrangente, proporcionando clareza e facilitando a compreensão dos desenvolvedores sobre como usar a API.
• Testes mais eficazes – As especificações da API podem ser usadas para gerar e executar testes automaticamente, o que ajuda a garantir que a implementação da API esteja em conformidade com o contrato e funcione conforme o esperado. Isso pode ajudar a identificar problemas em uma API antes que ela seja publicada no ambiente de produção.
• Segurança aprimorada – Ferramentas avançadas de segurança podem usar a Especificação OpenAPI para analisar o tráfego da API e o comportamento dos usuários. Elas podem aplicar segurança positiva<.htmla> verificando se as solicitações à API estão em conformidade com os métodos, endpoints e parâmetros compatíveis com o endpoint da API. O tráfego que não estiver em conformidade é bloqueado por padrão, reduzindo o número de chamadas que seus microsserviços precisam processar.
• Evolução mais fácil – As especificações de API podem ajudar a facilitar a evolução do contrato da API e da própria aplicação ao longo do tempo, fornecendo uma maneira clara e padronizada de documentar e comunicar alterações em formatos legíveis tanto por máquinas quanto por pessoas. Quando combinadas com práticas adequadas de versionamento, elas ajudam a minimizar os impactos das alterações na API sobre seus consumidores e garantem que a API permaneça retrocompatível.

De modo geral, o uso de uma especificação de API comum pode ajudar a melhorar a interoperabilidade, a documentação, os testes, a segurança e a evolução gradual de uma API.

Como o NGINX oferece suporte ao desenvolvimento de software API-first

O NGINX oferece um conjunto de ferramentas leves e nativas da nuvem que facilitam a operação, o monitoramento, a governança e a proteção de APIs em escala. Por exemplo, o API Connectivity Manager, que faz parte do F5 NGINX Management Suite, oferece um plano de gerenciamento unificado para suas operações de API. Com ele, você pode configurar e gerenciar gateways de API e portais de desenvolvedores. Como também é uma ferramenta que prioriza APIs, todas as funções podem ser acessadas por meio da API REST, facilitando a automação de CI/CD e a integração para as equipes de DevOps.

Com a Especificação OpenAPI, você pode usar os produtos NGINX para:

• Publique APIs no gateway de API
• Gerar documentação da API para o portal do desenvolvedor
• Aplique segurança positiva para proteger os endpoints da API

Use a Especificação OpenAPI para publicar uma API no gateway de API e a documentação no portal do desenvolvedor, além de definir políticas de segurança para o WAF por meio de pipelines de CI/CD ou da interface do usuário

Publique APIs no API Gateway

O API Connectivity Manager usa a Especificação OpenAPI para simplificar a publicação e o gerenciamento de APIs. Os desenvolvedores podem publicar APIs no gateway de API usando a interface do usuário do NGINX Management Suite ou a API REST totalmente declarativa. As APIs são adicionadas ao gateway como proxies de API, que contêm todas as configurações de entrada, backend e roteamento necessárias para que o gateway de API direcione as solicitações de API recebidas ao microsserviço de backend. Você pode usar a API REST para implantar e gerenciar APIs como código, criando scripts simples de automação de CI/CD com ferramentas como o Ansible.

Para obter instruções completas sobre como usar a Especificação OpenAPI para publicar uma API, consulte a documentação do API Connectivity Manager.

Gerar documentação da API para o Portal do Desenvolvedor

Manter a documentação costuma ser uma dor de cabeça para as equipes de API. No entanto, a documentação desatualizada nos portais de desenvolvedores também é um dos principais sinais da proliferação descontrolada de APIs. O API Connectivity Manager usa a Especificação OpenAPI para gerar automaticamente a documentação e publicá-la no portal do desenvolvedor, economizando o tempo dos desenvolvedores de API e garantindo que os consumidores de API sempre encontrem o que precisam. Você pode carregar arquivos da Especificação OpenAPI diretamente pela interface do usuário do API Connectivity Manager ou pela API REST.

Para obter instruções completas sobre como publicar a documentação da API no portal do desenvolvedor, consulte a documentação do API Connectivity Manager.

Aplique segurança positiva para proteger endpoints de API

Você também pode usar a Especificação OpenAPI para verificar se as solicitações de API enviadas ao gateway de API do NGINX Plus estão em conformidade com o que uma API oferece. Ao aplicar a segurança positiva (um modelo de segurança que define o que é permitido e bloqueia todo o resto), você pode impedir que solicitações mal-intencionadas sondem seus serviços de backend em busca de possíveis vulnerabilidades.

No momento da redação deste texto, não é possível usar o API Connectivity Manager para configurar o NGINX App Protect WAF; essa funcionalidade estará disponível posteriormente em 2023. No entanto, você pode usar o Instance Manager (outro módulo do NGINX Management Suite) e a Especificação OpenAPI para criar políticas personalizadas para seu WAF. Para obter mais informações, consulte a documentação do NGINX App Protect WAF e do Instance Manager.

Saiba mais sobre segurança de APIs e modelagem de ameaças, além de como aplicar autenticação e autorização no gateway de API, no Capítulo 7 de Mastering API Architecture.

Resumo

Uma abordagem API-first para a criação de microsserviços e aplicações pode beneficiar sua organização de várias maneiras. Alinhar as equipes em torno da Especificação OpenAPI (ou de outra especificação de API comum que seja legível tanto por humanos quanto por máquinas) ajuda a viabilizar a colaboração, a comunicação e as operações entre as equipes.

As aplicações modernas operam em ambientes complexos e nativos da nuvem. Adotar ferramentas que viabilizem uma abordagem API-first para a operação de APIs é uma etapa fundamental para concretizar sua estratégia API-first. Com o NGINX, você pode usar a Especificação OpenAPI para gerenciar suas APIs em escala, abrangendo equipes e ambientes distribuídos.

Inicie uma avaliação gratuita de 30 dias do NGINX Management Suite, que inclui acesso ao API Connectivity Manager, ao NGINX Plus como gateway de API e ao NGINX App Protect para proteger suas APIs.

Sobre o autor

Andrew Stiefel

Mais publicações de Andrew Stiefel