DEV Community

Cover image for Melhores Práticas de Nomenclatura para API REST: Guia Prático
Lucas
Lucas

Posted on Originally published at apidog.com

Melhores Práticas de Nomenclatura para API REST: Guia Prático

Convenções de nomeação para APIs REST que evitam dívida técnica

Abra uma base de código com mais de dois anos e você encontrará as cicatrizes: /getUser, /user_list, `[REDACTED PATH]

{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Experimente o Apidog hoje {% endcta %}

A nomeação é uma das decisões de design de API mais baratas — e uma das mais caras de reverter. Depois que clientes dependem de /getOrders, essa escolha pode permanecer por anos.

Este guia apresenta regras práticas para os principais elementos de uma API REST, com exemplos corretos e incorretos.

1. Use substantivos no plural para coleções

Uma URL nomeia um recurso, não uma operação. Como coleções são conjuntos de recursos, use substantivos no plural:

http
GET /v1/products
GET /v1/products/89
GET /v1/orders

Evite:

http
GET /v1/getProducts
GET /v1/product
GET /v1/productList

A mesma forma funciona para coleção e item: /products representa a coleção e /products/89, o produto 89 dentro dela.

A forma singular cria URLs inconsistentes, como /product para vários itens e /product/89 para um item. As diretrizes de API REST da Microsoft e APIs públicas como Stripe, GitHub e Shopify adotam a forma plural.

Exceção: recursos singleton. Se cada usuário tem exatamente um carrinho, `[REDACTED PATH]

2. Mantenha verbos fora dos caminhos

O método HTTP já representa a ação:

GET    /v1/orders/42
DELETE /v1/orders/42
PATCH  /v1/orders/42
Enter fullscreen mode Exit fullscreen mode

Evite:

GET  /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus
Enter fullscreen mode Exit fullscreen mode

Caminhos baseados em verbos aumentam a superfície da API. Um recurso com quatro operações se torna quatro endpoints diferentes para documentar, testar e armazenar em cache.

Com uma URL única, uma CDN consegue relacionar GET /v1/orders/42 e DELETE /v1/orders/42 ao mesmo recurso. URLs como /fetchOrder/42 e /deleteOrder/42 dificultam essa associação.

3. Use kebab-case nos caminhos

Para segmentos com várias palavras, use hífens:

/v1/gift-cards
/v1/shipping-addresses
Enter fullscreen mode Exit fullscreen mode

Evite:

/v1/giftCards
/v1/gift_cards
/v1/GiftCards
Enter fullscreen mode Exit fullscreen mode

Os hífens são reconhecidos como separadores de palavras por mecanismos de indexação. Sublinhados podem desaparecer quando uma URL é sublinhada em um e-mail ou documento. Além disso, camelCase favorece erros de diferenciação entre maiúsculas e minúsculas: /giftCards e /giftcards são URLs diferentes na maioria dos servidores.

As diretrizes REST da Zalando tornam o kebab-case uma regra obrigatória e aplicam esse padrão em centenas de serviços internos.

4. Escolha um padrão de maiúsculas e minúsculas para JSON

Tanto camelCase quanto snake_case funcionam. O problema é misturá-los.

Escolha uma opção e seja consistente:

{
  "orderId": 42,
  "createdAt": "2026-08-30T09:15:00Z",
  "totalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode

Ou:

{
  "order_id": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "total_amount": 4999
}
Enter fullscreen mode Exit fullscreen mode

Evite:

{
  "orderId": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "TotalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode
  • camelCase: mapeia bem para clientes JavaScript e Java.
  • snake_case: é fácil de escanear e combina com Ruby, Python e nomes de colunas SQL; o Stripe o usa em toda a API.

Escolha com base nos principais consumidores e registre a decisão no guia de estilo. Assim, a discussão acontece uma vez — e não em cada pull request.

Misturar padrões entre endpoints geralmente indica uma falha de governança, não uma preferência legítima de estilo. Consulte também as boas práticas de API REST para desenvolvedores.

5. Limite o aninhamento a dois níveis

O aninhamento pode expressar propriedade:

GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds
Enter fullscreen mode Exit fullscreen mode

Mas URLs profundas são difíceis de consumir:

GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

O cliente precisa carregar todos os IDs ancestrais para alcançar o recurso final, mesmo quando esse recurso tem um ID globalmente único.

Se um reembolso tem o ID 7, prefira:

GET /v1/refunds/7
Enter fullscreen mode Exit fullscreen mode

ou:

GET /v1/orders/1337/refunds/7
Enter fullscreen mode Exit fullscreen mode

Teste rápido: se uma URL contém três ou mais IDs, considere achatá-la. Depois que o pedido existe, /orders/1337 deve ser suficiente para identificá-lo.

6. Use parâmetros de consulta para filtros, ordenação e paginação

Caminhos identificam recursos. Parâmetros de consulta controlam como uma coleção é exibida:

GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000
Enter fullscreen mode Exit fullscreen mode

Evite:

GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate
Enter fullscreen mode Exit fullscreen mode

O padrão sort=-created_at, em que o prefixo - indica ordem decrescente, vem da especificação JSON:API e evita um segundo parâmetro como order=desc.

Filtros no caminho parecem simples até que seja necessário combiná-los. Nesse ponto, cada combinação pode virar um novo endpoint.

Escolha também um único padrão de paginação, como:

limit + cursor
Enter fullscreen mode Exit fullscreen mode

ou:

page + per_page
Enter fullscreen mode Exit fullscreen mode

Reutilize-o em todas as coleções. O guia de paginação de API detalha o trade-off entre paginação por cursor e por offset.

7. Versione a API no caminho

As duas opções mais comuns são:

/v1/products
Enter fullscreen mode Exit fullscreen mode

ou um cabeçalho:

Accept: application/vnd.myapi.v1+json
Enter fullscreen mode Exit fullscreen mode

O versionamento por cabeçalho é mais “puro” do ponto de vista REST, pois a URL continua nomeando o mesmo recurso. As diretrizes de design de API do Google reconhecem ambas as abordagens.

Na prática, o caminho costuma ser mais operacional:

  • aparece em cada linha de log;
  • pode ser testado diretamente no navegador;
  • é armazenado em cache sem configurações complexas de Vary;
  • não depende de o cliente lembrar de enviar um cabeçalho.

Use apenas versões principais:

/v1/products
/v2/products
Enter fullscreen mode Exit fullscreen mode

Evite:

/v1.2/products
Enter fullscreen mode Exit fullscreen mode

Alterações menores devem ser aditivas e não disruptivas. Para uma análise completa, incluindo negociação de conteúdo, consulte a comparação de estratégias de versionamento de API.

8. Trate IDs como opacos

IDs sequenciais expostos publicamente revelam volume e facilitam enumeração:

/orders/41
/orders/42
/orders/43
Enter fullscreen mode Exit fullscreen mode

Isso pode permitir que alguém percorra IDs em busca de recursos sem autorização adequada. A autorização em nível de objeto quebrada (BOLA) ocupa o primeiro lugar no OWASP API Security Top 10.

Prefira IDs opacos:

GET /v1/orders/ord_9f8e2a71b3
GET /v1[REDACTED PATH]b-41d4-a716-446655440000
Enter fullscreen mode Exit fullscreen mode

Evite, quando a enumeração for relevante:

GET /v1/orders/42
GET /v1/invoices/10883
Enter fullscreen mode Exit fullscreen mode

IDs aleatórios e prefixados, como ord_9f8e2a71b3, são autoexplicativos nos logs e difíceis de adivinhar. Ainda assim, verificações de autorização continuam obrigatórias. IDs opacos reduzem o impacto de uma falha; não substituem autorização.

Você pode manter chaves inteiras internamente. A regra se aplica aos IDs expostos nas URLs.

9. Modele ações não-CRUD como recursos de controlador

Algumas operações não têm um mapeamento CRUD claro:

  • cancelar um pedido;
  • tentar novamente um pagamento;
  • reenviar um e-mail.

Modele-as como ações sob o recurso:

POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry
Enter fullscreen mode Exit fullscreen mode

Evite:

PATCH /v1/orders/42
{ "status": "cancelled" }
Enter fullscreen mode Exit fullscreen mode

e:

POST /v1/cancelOrder
{ "orderId": 42 }
Enter fullscreen mode Exit fullscreen mode

Esse é o padrão de controlador e a principal exceção à regra de não usar verbos no caminho. O verbo aparece no final, com escopo sob o recurso que sofrerá a ação.

Cancelar um pedido pode:

  • iniciar um reembolso;
  • liberar estoque;
  • enviar notificações;
  • exigir um motivo;
  • ter permissões e auditoria próprias.

Um endpoint explícito como /cancel comunica a intenção e permite tratar esses requisitos separadamente.

10. Mantenha a consistência em cabeçalhos e parâmetros

Cabeçalhos personalizados devem usar Hyphenated-Pascal-Case:

Idempotency-Key: abc123
[REDACTED IDENTIFIER]
Enter fullscreen mode Exit fullscreen mode

Não use o antigo prefixo X-, descontinuado pelo RFC 6648 em 2012. Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas durante o envio, mas a documentação e os SDKs devem usar uma única forma.

Os parâmetros de consulta devem seguir o padrão do JSON. Se o corpo usa snake_case:

GET /v1/products?min_price=1000&created_after=2026-01-01
Enter fullscreen mode Exit fullscreen mode

Evite misturar:

GET /v1/products?minPrice=1000
Enter fullscreen mode Exit fullscreen mode

Um desenvolvedor que encontra created_at na resposta e precisa digitar createdAfter na consulta provavelmente errará — e todos os demais repetirão o problema.

Resumo das regras

# Regra Correto Errado
1 Use substantivos no plural para coleções /products, /products/89 /getProducts, /productList
2 Não use verbos nos caminhos DELETE /orders/42 POST /deleteOrder/42
3 Use kebab-case nos caminhos /gift-cards /giftCards, /gift_cards
4 Documente um padrão JSON order_id em todos os lugares orderId e order_id misturados
5 Limite o aninhamento a dois níveis /orders/1337/refunds `[REDACTED PATH]
6 Use parâmetros para filtros e paginação ?status=active&sort=-created_at /orders/active
7 Use uma versão principal no caminho /v1/products /v1.2/products, cabeçalhos esquecidos
8 Use IDs opacos /orders/ord_9f8e2a71b3 /orders/42 público e enumerável
9 Use o padrão de controlador para ações POST /orders/42/cancel PATCH com {"status":"cancelled"}
10 Seja consistente em cabeçalhos e parâmetros Idempotency-Key, ?min_price= X-IDEMPOTENCY_KEY, ?minPrice=

Como aplicar as convenções em escala

Um guia de estilo em uma wiki não é suficiente. APIs consistentes são projetadas e validadas antes de o código existir — esse é o objetivo da governança de API na prática.

O Apidog ajuda a aplicar esse processo:

  1. Defina endpoints em um designer visual orientado a esquemas.
  2. Torne caminhos, convenções de maiúsculas e minúsculas e parâmetros decisões explícitas.
  3. Crie componentes compartilhados para Pagination, Error e Money.
  4. Reutilize esses esquemas em todos os endpoints.
  5. Revise o design antes da implementação.
  6. Gere documentação, servidores mock e testes a partir da especificação.

Com workspaces de equipe e revisão incorporada, é possível detectar /getUserOrders durante o design, quando a renomeação custa um clique — e não depois que três clientes já dependem do endpoint.

Baixe o Apidog e experimente gratuitamente em seu próximo endpoint. Adaptar uma API antiga é difícil; manter padrões consistentes em APIs novas não precisa ser.

Perguntas frequentes

URLs REST devem usar plural ou singular?

Use plural para recursos com mais de uma instância:

http
/products
/orders
/users

A forma plural funciona tanto para a coleção quanto para um membro, como /orders/42. Reserve o singular para singletons verdadeiros, como `[REDACTED PATH]

Para entender melhor a modelagem de recursos, consulte o que é uma API REST.

camelCase ou snake_case é melhor para campos JSON?

Nenhum é universalmente melhor. camelCase pode ser mais conveniente para consumidores JavaScript; snake_case é legível e combina com Python, Ruby, SQL e com a API do Stripe.

A regra essencial é escolher um padrão, documentá-lo e aplicá-lo na revisão de esquemas. Misturar padrões prejudica mais do que qualquer uma das escolhas.

Devo colocar a versão da API na URL ou em um cabeçalho?

Use a URL, como /v1/orders, salvo se houver um requisito forte de hipermídia. A versão no caminho aparece em logs, caches e testes de navegador sem depender de configuração adicional do cliente.

Use apenas versões principais e implemente alterações menores de forma aditiva e não disruptiva.

Verbos são aceitáveis em um caminho REST?

Sim, para ações não-CRUD modeladas como endpoints de controlador:

POST /orders/42/cancel
POST /payments/pay_88a1/retry
Enter fullscreen mode Exit fullscreen mode

O verbo deve aparecer no final do caminho, com escopo sob o recurso, e o método deve ser POST. Nos demais casos, o método HTTP carrega o verbo e o caminho contém apenas substantivos.

Como a governança de API ajuda?

A governança de API transforma convenções em regras verificáveis durante o design, antes que inconsistências cheguem ao código e aos clientes.

Top comments (0)