Usando JSON em APIs REST: Melhores Práticas

2026-07-19· Tags: json, rest-api, api-design, json-best-practices, pagination, web-development

JSON em APIs REST

JSON e APIs REST são uma combinação perfeita. A sintaxe leve do JSON, o suporte nativo a arrays e o suporte universal de linguagens o tornam o formato padrão para APIs web modernas. Mas simplesmente usar JSON em sua API não é suficiente -- seguir convenções estabelecidas e melhores práticas garante que sua API seja consistente, intuitiva e fácil de integrar.

Formato de Requisição e Resposta

Estrutura de Envelope Consistente

Adote um envelope JSON consistente para todas as respostas da API. Isso torna o processamento no lado do cliente previsível e simplifica o tratamento de erros.

{
  "status": "success",
  "data": {
    "user": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    }
  },
  "meta": {
    "requestId": "req-a1b2c3d4",
    "timestamp": "2026-07-19T10:30:00Z"
  }
}

Snake Case vs Camel Case

Escolha uma convenção de nomenclatura e mantenha-a em toda a sua API:

Camel Case (createdAt, firstName): Comum em ecossistemas JavaScript/TypeScript
Snake Case (created_at, first_name): Comum em ecossistemas Python, Ruby e PHP

Qualquer que seja sua escolha, documente-a claramente e considere usar uma camada de transformação se sua linguagem de backend usar uma convenção diferente.

Códigos de Status HTTP com JSON

Códigos de status HTTP adequados complementam suas respostas JSON. Use-os de forma consistente:

| Código de Status | Significado | Quando Usar | |-------------|---------|-------------| | 200 OK | Sucesso | Sucesso em GET, PUT, PATCH | | 201 Created | Recurso criado | Sucesso em POST | | 204 No Content | Sucesso na exclusão | Sucesso em DELETE (sem corpo JSON) | | 400 Bad Request | Sintaxe JSON inválida | Corpo da requisição malformado | | 401 Unauthorized | Autenticação necessária | Token ausente ou inválido | | 403 Forbidden | Permissões insuficientes | Autenticação válida, mas não permitido | | 404 Not Found | Recurso não existe | ID ou caminho inválido | | 422 Unprocessable Entity | Falha na validação | Erros semânticos em JSON válido | | 429 Too Many Requests | Limite de taxa atingido | Cliente excedendo os limites | | 500 Internal Server Error | Falha no servidor | Erros inesperados |

Formato Padrão de Resposta de Erro

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request body contains invalid fields",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be a positive integer",
        "code": "OUT_OF_RANGE"
      }
    ]
  }
}

Recursos Aninhados

Representando Relacionamentos

As APIs REST frequentemente precisam representar recursos relacionados. Aqui estão os padrões comuns:

Incorporado (carregamento ansioso):

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customer": {
      "id": 123,
      "name": "Alice",
      "email": "alice@example.com"
    },
    "items": [
      {
        "productId": 42,
        "name": "Widget",
        "quantity": 2,
        "price": 14.99
      }
    ]
  }
}

Referenciado (carregamento preguiçoso) -- use IDs e forneça endpoints separados:

{
  "order": {
    "id": 5001,
    "total": 29.99,
    "customerId": 123,
    "itemIds": [101, 102]
  }
}

Regra prática: Incorpore dados relacionados que são sempre necessários em conjunto. Referencie dados que são recuperados condicionalmente ou em momentos diferentes.

Padrões de Paginação

Ao retornar listas de recursos, a paginação é essencial. Use um formato de paginação consistente:

Paginação Baseada em Offset

{
  "status": "success",
  "data": [
    { "id": 1, "name": "User 1" },
    { "id": 2, "name": "User 2" }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 156,
    "totalPages": 8,
    "links": {
      "first": "/api/users?page=1&perPage=20",
      "prev": null,
      "next": "/api/users?page=2&perPage=20",
      "last": "/api/users?page=8&perPage=20"
    }
  }
}

Paginação Baseada em Cursor (Recomendada para Grandes Conjuntos de Dados)

{
  "status": "success",
  "data": [
    { "id": 100, "name": "User 100" },
    { "id": 101, "name": "User 101" }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6MTAxfQ==",
    "hasMore": true
  }
}

A paginação baseada em cursor é mais confiável para dados em tempo real, onde novos registros podem deslocar os limites das páginas.

JSON em Requisições de API

Corpos de Requisição POST / PUT

Aceite JSON com o cabeçalho Content-Type: application/json:

{
  "title": "New Blog Post",
  "content": "This is the content...",
  "tags": ["json", "rest-api"],
  "published": false
}

Atualizações Parciais com PATCH

Use PATCH para atualizações parciais. Aceite apenas os campos que devem ser alterados:

// PATCH /api/users/123
{
  "email": "newemail@example.com"
}

Filtragem, Ordenação e Pesquisa

Use parâmetros de consulta para manipulação de dados, mantendo o corpo JSON limpo:

GET /api/users?filter[role]=admin&sort=-createdAt&search=alice

{
  "status": "success",
  "data": [ /* filtered, sorted results */ ]
}

Limitação de Taxa

Inclua informações de limite de taxa nos cabeçalhos de resposta e, opcionalmente, no corpo JSON:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  },
  "meta": {
    "rateLimit": {
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-07-19T11:00:00Z"
    }
  }
}

Lista de Verificação de Melhores Práticas de JSON

[ ] Use nomenclatura de chaves consistente (camelCase ou snake_case em todo o projeto)
[ ] Retorne códigos de status HTTP apropriados em cada resposta
[ ] Inclua um formato de erro consistente com códigos de erro legíveis por máquina
[ ] Pagine endpoints de listas com um objeto de paginação padronizado
[ ] Use JSON Schema para documentar e validar estruturas de requisição/resposta
[ ] Defina Content-Type: application/json em todos os endpoints JSON
[ ] Comprima respostas JSON com gzip ou brotli em produção
[ ] Imponha limites máximos de tamanho de payload (por exemplo, padrão de 1MB)
[ ] Use HTTPS para criptografar dados JSON em trânsito
[ ] Estruture detalhes de erro para ajudar os clientes a depurar sem expor detalhes internos

Validando o JSON da Sua API

Execute as respostas da sua API por meio de um validador de JSON para detectar erros de formatação antes que cheguem aos clientes. Respostas JSON consistentes e válidas tornam sua API confiável e amigável para desenvolvedores. Use nossa ferramenta Formatador e Validador de JSON para testar seus payloads durante o desenvolvimento.