O que Princípios de Design de API faz?
Domine os princípios de design de APIs REST e GraphQL para criar APIs intuitivas, escaláveis e fáceis de manter que encantam os desenvolvedores e resistem ao teste do tempo.
Quando Usar Este Skill
- Projetar novas APIs REST ou GraphQL
- Refatorar APIs existentes para melhor usabilidade
- Estabelecer padrões de design de API para sua equipe
- Revisar especificações de API antes da implementação
- Migrar entre paradigmas de API (REST para GraphQL, etc.)
- Criar documentação de API amigável para desenvolvedores
- Otimizar APIs para casos de uso específicos (mobile, integrações de terceiros)
Conceitos Principais
1. Princípios de Design RESTful
Arquitetura Orientada a Recursos
- Recursos são substantivos (usuários, pedidos, produtos), não verbos
- Use métodos HTTP para ações (GET, POST, PUT, PATCH, DELETE)
- URLs representam hierarquias de recursos
- Convenções de nomenclatura consistentes
Semântica dos Métodos HTTP:
GET: Recuperar recursos (idempotente, seguro)POST: Criar novos recursosPUT: Substituir recurso inteiro (idempotente)PATCH: Atualizações parciais de recursosDELETE: Remover recursos (idempotente)
2. Princípios de Design GraphQL
Desenvolvimento Schema-First
- Tipos definem seu modelo de domínio
- Queries para leitura de dados
- Mutações para modificação de dados
- Assinaturas para atualizações em tempo real
Estrutura de Query:
- Clientes solicitam exatamente o que precisam
- Único endpoint, múltiplas operações
- Schema fortemente tipado
- Introspecção embutida
3. Estratégias de Versionamento de API
Versionamento por URL:
/api/v1/usuarios
/api/v2/usuarios
Versionamento por Cabeçalho:
Accept: application/vnd.api+json; version=1
Versionamento por Parâmetro de Query:
/api/usuarios?version=1
Padrões de Design de API REST
Padrão 1: Design de Coleção de Recursos
# Bom: Endpoints orientados a recursos
GET /api/usuarios # Listar usuários (com paginação)
POST /api/usuarios # Criar usuário
GET /api/usuarios/{id} # Obter usuário específico
PUT /api/usuarios/{id} # Substituir usuário
PATCH /api/usuarios/{id} # Atualizar campos do usuário
DELETE /api/usuarios/{id} # Excluir usuário
# Recursos aninhados
GET /api/usuarios/{id}/pedidos # Obter pedidos do usuário
POST /api/usuarios/{id}/pedidos # Criar pedido para o usuário
# Ruim: Endpoints orientados a ação (evitar)
POST /api/criarUsuario
POST /api/obterUsuarioPorId
POST /api/excluirUsuario
Padrão 2: Paginação e Filtragem
from typing import List, Optional
from pydantic import BaseModel, Field
class ParametrosPaginacao(BaseModel):
pagina: int = Field(1, ge=1, description="Número da página")
tamanho_pagina: int = Field(20, ge=1, le=100, description="Itens por página")
class ParametrosFiltro(BaseModel):
status: Optional[str] = None
criado_apos: Optional[str] = None
busca: Optional[str] = None
class RespostaPaginada(BaseModel):
itens: List[dict]
total: int
pagina: int
tamanho_pagina: int
paginas: int
@property
def tem_proximo(self) -> bool:
return self.pagina < self.paginas
@property
def tem_anterior(self) -> bool:
return self.pagina > 1
# Exemplo de endpoint FastAPI
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/usuarios", response_model=RespostaPaginada)
async def listar_usuarios(
pagina: int = Query(1, ge=1),
tamanho_pagina: int = Query(20, ge=1, le=100),
status: Optional[str] = Query(None),
busca: Optional[str] = Query(None)
):
# Aplicar filtros
consulta = construir_consulta(status=status, busca=busca)
# Contar total
total = await contar_usuarios(consulta)
# Buscar página
deslocamento = (pagina - 1) * tamanho_pagina
usuarios = await buscar_usuarios(consulta, limite=tamanho_pagina, deslocamento=deslocamento)
return RespostaPaginada(
itens=usuarios,
total=total,
pagina=pagina,
tamanho_pagina=tamanho_pagina,
paginas=(total + tamanho_pagina - 1) // tamanho_pagina
)
Padrão 3: Tratamento de Erros e Códigos de Status
from fastapi import HTTPException, status
from pydantic import BaseModel
from typing import Any
class RespostaErro(BaseModel):
erro: str
mensagem: str
detalhes: Optional[dict] = None
timestamp: str
caminho: str
class DetalheErroValidacao(BaseModel):
campo: str
mensagem: str
valor: Any
# Respostas de erro consistentes
CODIGOS_STATUS = {
"sucesso": 200,
"criado": 201,
"sem_conteudo": 204,
"requisicao_invalida": 400,
"nao_autorizado": 401,
"proibido": 403,
"nao_encontrado": 404,
"conflito": 409,
"nao_processavel": 422,
"erro_interno": 500
}
def levantar_nao_encontrado(recurso: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"erro": "NaoEncontrado",
"mensagem": f"{recurso} não encontrado",
"detalhes": {"id": id}
}
)
def levantar_erro_validacao(erros: List[DetalheErroValidacao]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"erro": "ErroValidacao",
"mensagem": "Falha na validação da requisição",
"detalhes": {"erros": [e.dict() for e in erros]}
}
)
# Exemplo de uso
@app.get("/api/usuarios/{usuario_id}")
async def obter_usuario(usuario_id: str):
usuario = await buscar_usuario(usuario_id)
if not usuario:
levantar_nao_encontrado("Usuário", usuario_id)
return usuario
Padrão 4: HATEOAS (Hypermedia as the Engine of Application State)
class RespostaUsuario(BaseModel):
id: str
nome: str
email: str
_links: dict
@classmethod
def de_usuario(cls, usuario: Usuario, url_base: str):
return cls(
id=usuario.id,
nome=usuario.nome,
email=usuario.email,
_links={
"self": {"href": f"{url_base}/api/usuarios/{usuario.id}"},
"pedidos": {"href": f"{url_base}/api/usuarios/{usuario.id}/pedidos"},
"atualizar": {
"href": f"{url_base}/api/usuarios/{usuario.id}",
"method": "PATCH"
},
"excluir": {
"href": f"{url_base}/api/usuarios/{usuario.id}",
"method": "DELETE"
}
}
)
Padrões de Design GraphQL
Padrão 1: Design de Schema
# schema.graphql
# Definições de tipo claras
type Usuario {
id: ID!
email: String!
nome: String!
criadoEm: DateTime!
# Relacionamentos
pedidos(primeiro: Int = 20, depois: String, status: StatusPedido): ConexaoPedido!
perfil: PerfilUsuario
}
type Pedido {
id: ID!
status: StatusPedido!
total: Dinheiro!
itens: [ItemPedido!]!
criadoEm: DateTime!
# Referência inversa
usuario: Usuario!
}
# Padrão de paginação (estilo Relay)
type ConexaoPedido {
arestas: [ArestaPedido!]!
infoPagina: InfoPagina!
totalContagem: Int!
}
type ArestaPedido {
no: Pedido!
cursor: String!
}
type InfoPagina {
temProximaPagina: Boolean!
temPaginaAnterior: Boolean!
cursorInicio: String
cursorFim: String
}
# Enums para segurança de tipos
enum StatusPedido {
PENDENTE
CONFIRMADO
ENVIADO
ENTREGUE
CANCELADO
}
# Scalars customizados
scalar DateTime
scalar Dinheiro
# Raiz de Query
type Query {
usuario(id: ID!): Usuario
usuarios(primeiro: Int = 20, depois: String, busca: String): ConexaoUsuario!
pedido(id: ID!): Pedido
}
# Raiz de Mutation
type Mutation {
criarUsuario(input: CriarUsuarioInput!): CriarUsuarioPayload!
atualizarUsuario(input: AtualizarUsuarioInput!): AtualizarUsuarioPayload!
excluirUsuario(id: ID!): ExcluirUsuarioPayload!
criarPedido(input: CriarPedidoInput!): CriarPedidoPayload!
}
# Tipos de input para mutações
input CriarUsuarioInput {
email: String!
nome: String!
senha: String!
}
# Tipos de payload para mutações
type CriarUsuarioPayload {
usuario: Usuario
erros: [Erro!]
}
type Erro {
campo: String
mensagem: String!
}
Padrão 2: Design de Resolvers
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
tipo_usuario = ObjectType("Usuario")
@query.field("usuario")
async def resolver_usuario(obj, info, id: str) -> Optional[dict]:
"""Resolve um único usuário por ID."""
return await buscar_usuario_por_id(id)
@query.field("usuarios")
async def resolver_usuarios(
obj,
info,
primeiro: int = 20,
depois: Optional[str] = None,
busca: Optional[str] = None
) -> dict:
"""Resolve lista paginada de usuários."""
# Decodificar cursor
deslocamento = decodificar_cursor(depois) if depois else 0
# Buscar usuários
usuarios = await buscar_usuarios(
limite=primeiro + 1, # Buscar um extra para verificar temProximaPagina
deslocamento=deslocamento,
busca=busca
)
# Paginação
tem_proximo = len(usuarios) > primeiro
if tem_proximo:
usuarios = usuarios[:primeiro]
arestas = [
{
"no": usuario,
"cursor": codificar_cursor(deslocamento + i)
}
for i, usuario in enumerate(usuarios)
]
return {
"arestas": arestas,
"infoPagina": {
"temProximaPagina": tem_proximo,
"temPaginaAnterior": deslocamento > 0,
"cursorInicio": arestas[0]["cursor"] if arestas else None,
"cursorFim": arestas[-1]["cursor"] if arestas else None
},
"totalContagem": await contar_usuarios(busca=busca)
}
@tipo_usuario.field("pedidos")
async def resolver_pedidos_usuario(usuario: dict, info, primeiro: int = 20) -> dict:
"""Resolve pedidos do usuário (prevenção N+1 com DataLoader)."""
# Usar DataLoader para agrupar requisições
carregador = info.context["carregadores"]["pedidos_por_usuario"]
pedidos = await carregador.load(usuario["id"])
return paginar_pedidos(pedidos, primeiro)
@mutation.field("criarUsuario")
async def resolver_criar_usuario(obj, info, input: dict) -> dict:
"""Cria novo usuário."""
try:
# Validar input
validar_input_usuario(input)
# Criar usuário
usuario = await criar_usuario(
email=input["email"],
nome=input["nome"],
senha=hash_senha(input["senha"])
)
return {
"usuario": usuario,
"erros": []
}
except ErroValidacao as e:
return {
"usuario": None,
"erros": [{"campo": e.campo, "mensagem": e.mensagem}]
}
Padrão 3: DataLoader (Prevenção do Problema N+1)
from aiodataloader import DataLoader
from typing import List, Optional
class CarregadorUsuario(DataLoader):
"""Carrega usuários em lote por ID."""
async def batch_load_fn(self, ids_usuario: List[str]) -> List[Optional[dict]]:
"""Carrega múltiplos usuários em uma única consulta."""
usuarios = await buscar_usuarios_por_ids(ids_usuario)
# Mapear resultados de volta à ordem do input
mapa_usuarios = {usuario["id"]: usuario for usuario in usuarios}
return [mapa_usuarios.get(id_usuario) for id_usuario in ids_usuario]
class CarregadorPedidosPorUsuario(DataLoader):
"""Carrega pedidos em lote por ID do usuário."""
async def batch_load_fn(self, ids_usuario: List[str]) -> List[List[dict]]:
"""Carrega pedidos para múltiplos usuários em uma única consulta."""
pedidos = await buscar_pedidos_por_ids_usuario(ids_usuario)
# Agrupar pedidos por usuario_id
pedidos_por_usuario = {}
for pedido in pedidos:
usuario_id = pedido["usuario_id"]
if usuario_id not in pedidos_por_usuario:
pedidos_por_usuario[usuario_id] = []
pedidos_por_usuario[usuario_id].append(pedido)
# Retornar na ordem do input
return [pedidos_por_usuario.get(id_usuario, []) for id_usuario in ids_usuario]
# Configuração do contexto
def criar_contexto():
return {
"carregadores": {
"usuario": CarregadorUsuario(),
"pedidos_por_usuario": CarregadorPedidosPorUsuario()
}
}
Melhores Práticas
APIs REST
- Nomenclatura Consistente: Use substantivos no plural para coleções (
/usuarios, não/usuario) - Sem Estado (Stateless): Cada requisição contém todas as informações necessárias
- Use Códigos de Status HTTP Corretamente: 2xx sucesso, 4xx erros do cliente, 5xx erros do servidor
- Versionar Sua API: Planeje mudanças disruptivas desde o primeiro dia
- Paginação: Sempre pagine grandes coleções
- Limitação de Taxa (Rate Limiting): Proteja sua API com limites de requisição
- Documentação: Use OpenAPI/Swagger para documentação interativa
APIs GraphQL
- Schema Primeiro: Projete o schema antes de escrever resolvers
- Evite N+1: Use DataLoaders para busca eficiente de dados
- Validação de Input: Valide nos níveis de schema e resolver
- Tratamento de Erros: Retorne erros estruturados nos payloads de mutação
- Paginação: Use paginação baseada em cursor (especificação Relay)
- Depreciação: Use a diretiva
@deprecatedpara migração gradual - Monitoramento: Acompanhe a complexidade das consultas e o tempo de execução
Armadilhas Comuns
- Over-fetching/Under-fetching (REST): Resolvido no GraphQL, mas requer DataLoaders
- Mudanças Disruptivas: Versione APIs ou use estratégias de depreciação
- Formatos de Erro Inconsistentes: Padronize as respostas de erro
- Limitação de Taxa Ausente: APIs sem limites são vulneráveis a abusos
- Documentação Pobre: APIs não documentadas frustram desenvolvedores
- Ignorar Semântica HTTP: POST para operações idempotentes quebra expectativas
- Acoplamento Forte: Estrutura da API não deve espelhar o schema do banco de dados
Recursos
- referencias/melhores-praticas-rest.md: Guia abrangente de design de API REST
- referencias/design-schema-graphql.md: Padrões e antipadrões de schema GraphQL
- referencias/estrategias-versionamento-api.md: Abordagens de versionamento e caminhos de migração
- assets/modelo-api-rest.py: Modelo de API REST com FastAPI
- assets/modelo-schema-graphql.graphql: Exemplo completo de schema GraphQL
- assets/lista-verificacao-design-api.md: Lista de verificação de revisão pré-implementação
- scripts/gerador-openapi.py: Gere especificações OpenAPI a partir do código