Noções Básicas de Design de API

8 exemplos para você começar com o Design de API para backends Node.js - 6 básicos e 2 intermediários.

Pré-requisitos

Express 5 ou Fastify 5 com análise de corpo JSON e Zod instalados.

npm install express@5 zod

Exemplos Básicos

1. URLs Orientadas a Recursos

GET    /v1/orders
POST   /v1/orders
GET    /v1/orders/:id
PATCH  /v1/orders/:id
DELETE /v1/orders/:id

• Substantivos nos caminhos; verbos vêm dos métodos HTTP
• Recursos aninhados apenas um nível abaixo: /v1/orders/:id/items
• Evite caminhos no estilo RPC /createOrder em APIs REST públicas

Relacionado: Versionamento e Descontinuação - Prefixo /v1

2. Envelope JSON Consistente

{ "data": { "id": "ord_1", "status": "pending" } }

{ "error": { "code": "ORDER_NOT_FOUND", "message": "Order ord_99 not found" } }

• Respostas de sucesso envolvem a carga útil em data
• Erros usam o objeto error com code estável para clientes
• Listas retornam data como um array mais metadados de paginação

Relacionado: Padrões de Resposta de Erro - Detalhes do Problema

3. Códigos de Status Corretos

• Não retorne 200 com { error: ... } no corpo
• 422 aceitável para validação semântica se a equipe padronizar

4. Validação Zod na Fronteira

import { z } from "zod";
import express from "express";
 
const createOrderBody = z.object({
  customerId: z.string().uuid(),
  sku: z.string().min(1),
  qty: z.number().int().positive(),
});
 
const app = express();
app.use(express.json());
 
app.post("/v1/orders", (req, res) => {
  const parsed = createOrderBody.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({
      error: { code: "VALIDATION_ERROR", details: parsed.error.flatten() },
    });
  }
  res.status(201).json({ data: { id: crypto.randomUUID(), ...parsed.data } });
});

• JSON inválido nunca chega aos casos de uso
• Retorne detalhes por campo para clientes de formulário
• Compartilhe esquemas com o frontend sempre que possível

5. Semântica Idempotente de PUT/PATCH

PATCH /v1/orders/ord_1
{ "status": "shipped" }

• PATCH atualização parcial; documente os campos permitidos
• PUT substituição completa quando você a suportar - raro em APIs B2B
• Use o cabeçalho Idempotency-Key em pagamentos POST (veja intermediário)

6. Prévia de Parâmetros de Consulta de Paginação

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMifQ

• Prefira paginação por cursor para tabelas grandes
• Offset aceitável para telas de administração com pequenos conjuntos de dados

Relacionado: Paginação e Filtragem - cursor vs offset

Exemplos Intermediários

7. Negociação de Conteúdo e Apenas JSON

app.use((req, res, next) => {
  if (req.method === "POST" && !req.is("application/json")) {
    return res.status(415).json({ error: { code: "UNSUPPORTED_MEDIA_TYPE" } });
  }
  next();
});

• APIs públicas padronizam em application/json
• Webhooks verificam Content-Type e assinatura separadamente

8. Stub OpenAPI a partir de Rotas

Documente as rotas à medida que você as envia.

paths:
  /v1/orders:
    post:
      summary: Create order
      responses:
        "201":
          description: Created

• OpenAPI escrito à mão ou gerado por código evita desvios

Relacionado: OpenAPI & Swagger - spec-first vs code-first

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.