Visão geral

A loja tem um front-end web, um aplicativo mobile e um serviço de pedidos, e os três precisam dos dados de produtos mantidos pelo serviço de produtos. Como cada um deles sabe qual URL chamar, o que enviar e o que recebe de volta? E o que acontece com eles quando o time de produtos reescrever o serviço no próximo semestre? A resposta para as duas perguntas é a API.

Uma API (Application Programming Interface) é um contrato que define como dois componentes de software se comunicam. Ela especifica quais operações estão disponíveis, quais entradas aceitam e quais saídas retornam — sem expor a implementação interna.

No contexto de microsserviços, as APIs são o principal mecanismo de integração: os serviços expõem APIs, os clientes as consomem, e os times evoluem cada lado de forma independente, desde que o contrato seja respeitado. Uma fronteira de API estável significa que a implementação por trás dela pode ser totalmente substituída sem impactar nenhum consumidor.

flowchart LR
    consumer["Cliente\n(mobile, navegador, serviço)"]
    api["API\n(contrato)"]:::highlighted
    impl["Implementação\n(linguagem, BD, framework)"]

    consumer -->|"requisição"| api
    api -->|"resposta"| consumer
    api -->|"esconde"| impl
    consumer -.-x|"não enxerga"| impl

    classDef highlighted fill:#fcc

Roteiro

1. Esta página — o que é um contrato de API, por que ele importa, os principais estilos de API e quão RESTful uma API é.
2. Design de APIs REST — recursos, métodos, idempotência, códigos de status, erros, paginação e versionamento.
3. OpenAPI & Swagger — descrever o contrato em um documento legível por máquina e servi-lo com o springdoc.

Slides

Clique nos slides e use ← → para navegar; F abre em tela cheia e P abre a visão do apresentador, com as notas. Abrir os slides em uma nova aba

Por que APIs importam

O contrato na nossa plataforma

O hands-on torna o contrato concreto. No Hands-on 1, o microsserviço Account é dividido em dois módulos Maven:

Como o serviço de autenticação (Hands-on 3) depende apenas do módulo account, o time de accounts pode mudar livremente o banco de dados, o modelo ou a lógica do serviço. Apenas uma mudança em AccountController, AccountIn ou AccountOut é visível para os outros — e é exatamente essa a mudança que precisa ser negociada e, se quebrar clientes, versionada (veja Versionamento).

Tipos de APIs

A mesma operação — "me dê o produto 42" — fica bem diferente em cada um dos três estilos de requisição/resposta:

GET /products/42 HTTP/1.1
Accept: application/json

service ProductService {
  rpc GetProduct (GetProductRequest) returns (Product);
}
message GetProductRequest { string id = 1; }
message Product { string id = 1; string name = 2; double price = 3; }

query {
  product(id: "42") { name price }
}

Como escolher. Para a API pública da loja (navegadores, aplicativos mobile, parceiros), REST é o padrão: ferramentas universais, GETs cacheáveis, fácil de depurar. gRPC compensa em chamadas internas frequentes, em que a latência e o tamanho do payload importam. GraphQL se encaixa em um front-end que compõe dados de muitos serviços. Mensageria é a escolha quando o produtor não deve esperar pelo consumidor — tema de Arquitetura Orientada a Eventos.

Maturidade REST (Modelo de Richardson)³

Nem todas as APIs HTTP são igualmente RESTful. Leonard Richardson definiu um modelo de maturidade com quatro níveis:

POX significa "Plain Old XML": a requisição HTTP é só um túnel para uma chamada de procedimento remoto. HATEOAS significa "Hypermedia As The Engine Of Application State": o cliente descobre o que pode fazer em seguida a partir dos links na resposta, como uma pessoa faz ao navegar em um site.

A maioria das APIs REST em produção opera no nível 2. O nível 3 é raro na prática, tanto em microsserviços internos quanto em APIs públicas; a API REST do PayPal é um exemplo conhecido que retorna links com rel e href nas respostas.

Este curso foca em REST nível 2 e na documentação de APIs com OpenAPI / Swagger.

Tópicos abordados

Pontos-chave

• Uma API é um contrato: os consumidores dependem dele, nunca da implementação por trás dele.
• No hands-on, o contrato é um módulo separado (account: interface + DTOs) da implementação (account-service).
• REST sobre HTTP é o padrão para APIs web; gRPC, GraphQL, WebSocket e mensageria resolvem necessidades específicas.
• A maioria das APIs está no nível 2 de Richardson: recursos + métodos HTTP + códigos de status. REST foi definido por Roy Fielding² sobre a semântica do HTTP¹.
• Nunca exponha entidades; mudar um DTO é mudar o contrato.

Conexões

• Construa o contrato e sua implementação: Hands-on 1 — CRUD.
• Encaminhe clientes externos para as APIs: Hands-on 2 — Gateway.
• Projete suas próprias APIs: exercícios Product API e Order API.
• APIs assíncronas: Arquitetura Orientada a Eventos. Como os serviços se encaixam: Microsserviços.