JSON1
Voltar à Base de Conhecimento|Voltar às Ferramentas JSON

Melhores Práticas para API JSON

Guia completo para projetar APIs JSON de alta qualidade, fáceis de manter e amigáveis ao usuário

Princípios de Design de API

Princípios Fundamentais

  • • Consistência: Nomenclatura e estrutura padronizadas
  • • Previsibilidade: Desenvolvedores podem antecipar o comportamento da API
  • • Simplicidade: Evitar complexidade desnecessária
  • • Escalabilidade: Suporte a expansões futuras de funcionalidades
  • • Compatibilidade: Proteger integrações existentes

Estilo de Design RESTful

Seguir o estilo arquitetural REST torna a API mais intuitiva e padronizada:

  • • Design de URL orientado a recursos
  • • Uso correto de métodos HTTP
  • • Comunicação sem estado
  • • Arquitetura de sistema em camadas

Convenções de Nomenclatura

Padrões de Caminho de URL

Práticas Recomendadas

GET /api/v1/usuarios
GET /api/v1/usuarios/123
POST /api/v1/usuarios
PUT /api/v1/usuarios/123
DELETE /api/v1/usuarios/123

GET /api/v1/usuarios/123/pedidos
GET /api/v1/pedidos?usuario_id=123

Práticas a Evitar

GET /api/v1/obterUsuarios
POST /api/v1/criarUsuario
GET /api/v1/lista_usuarios
GET /api/v1/Usuarios/123/Pedidos
DELETE /api/v1/removerUsuario/123

GET /obterDadosUsuario?id=123

Explicação das Regras de Nomenclatura

  • • Use substantivos no plural para representar coleções de recursos: /usuarios, /pedidos
  • • Use letras minúsculas e hífens: /perfis-usuario
  • • Evite verbos, deixe os métodos HTTP expressarem a operação
  • • Recursos aninhados devem refletir relacionamentos lógicos
  • • Use parâmetros de consulta para filtragem e ordenação

Nomenclatura de Campos JSON

Recomendado: snake_case

{
  "id_usuario": 123,
  "primeiro_nome": "João",
  "ultimo_nome": "Silva",
  "endereco_email": "usuario@exemplo.com",
  "criado_em": "2024-01-01T00:00:00Z",
  "esta_ativo": true,
  "url_imagem_perfil": "https://..."
}

Também aceitável: camelCase

{
  "idUsuario": 123,
  "primeiroNome": "João",
  "ultimoNome": "Silva",
  "enderecoEmail": "usuario@exemplo.com",
  "criadoEm": "2024-01-01T00:00:00Z",
  "estaAtivo": true,
  "urlImagemPerfil": "https://..."
}

Uso de Métodos HTTP

GET

Obter recursos

Características: Seguro, idempotente, cacheável

GET /api/v1/usuarios - Obter lista de usuáriosGET /api/v1/usuarios/123 - Obter usuário específicoGET /api/v1/usuarios?pagina=2&limite=20 - Obter com paginação
POST

Criar recursos

Características: Não seguro, não idempotente, não cacheável

POST /api/v1/usuarios - Criar novo usuárioPOST /api/v1/usuarios/123/pedidos - Criar pedido para usuárioPOST /api/v1/auth/login - Login de usuário
PUT

Atualização completa de recursos

Características: Não seguro, idempotente, não cacheável

PUT /api/v1/usuarios/123 - Atualizar completamente informações do usuárioPUT /api/v1/usuarios/123/senha - Atualizar senha
PATCH

Atualização parcial de recursos

Características: Não seguro, não idempotente, não cacheável

PATCH /api/v1/usuarios/123 - Atualizar parcialmente informações do usuárioPATCH /api/v1/usuarios/123/status - Atualizar status do usuário
DELETE

Excluir recursos

Características: Não seguro, idempotente, não cacheável

DELETE /api/v1/usuarios/123 - Excluir usuárioDELETE /api/v1/usuarios/123/sessoes - Excluir sessões do usuário

Tratamento de Erros

Formato Unificado de Resposta de Erro

{
  "erro": {
    "codigo": "VALIDACAO_FALHOU",
    "mensagem": "Falha na validação dos dados da solicitação",
    "detalhes": [
      {
        "campo": "email",
        "mensagem": "Formato de email incorreto"
      },
      {
        "campo": "senha",
        "mensagem": "Senha deve ter pelo menos 8 caracteres"
      }
    ],
    "timestamp": "2024-01-01T12:00:00Z",
    "id_solicitacao": "req_123456"
  }
}

Explicação dos Campos de Resposta de Erro

  • • codigo: Código de erro legível por máquina
  • • mensagem: Descrição de erro legível por humanos
  • • detalhes: Informações detalhadas do erro (opcional)
  • • timestamp: Hora em que o erro ocorreu
  • • id_solicitacao: ID da solicitação para rastreamento de logs

Tipos Comuns de Erro

  • • SOLICITACAO_INVALIDA - Formato de solicitação incorreto
  • • VALIDACAO_FALHOU - Falha na validação de dados
  • • AUTENTICACAO_NECESSARIA - Requer autenticação
  • • PERMISSAO_NEGADA - Permissões insuficientes
  • • RECURSO_NAO_ENCONTRADO - Recurso não existe
  • • LIMITE_TAXA_EXCEDIDO - Excedeu limite de taxa

Melhores Práticas de Tratamento de Erros

  • • Fornecer descrições de erro claras
  • • Incluir sugestões para resolver problemas
  • • Usar formato de erro consistente
  • • Evitar exposição de informações sensíveis
  • • Fornecer ID de solicitação para rastreamento
  • • Códigos de status HTTP apropriados

Referência Rápida

Padrões Comuns de Design de API

GET /api/v1/usuarios?pagina=1&limite=20GET /api/v1/usuarios?ordenar=criado_em&ordem=descGET /api/v1/usuarios?filtro[status]=ativoGET /api/v1/usuarios?incluir=perfil,pedidos

Ferramentas Relacionadas

Ler em outro idioma