Nomes de Recursos REST API: Plural ou Singular?

TL;DR

Os nomes dos recursos da API REST devem ser plurais. Use /pets/{id} e não /pet/{id}. Nomes plurais representam coleções de forma consistente, se alinham com a semântica HTTP e correspondem à forma como os desenvolvedores pensam sobre os recursos. A Modern PetstoreAPI usa nomes plurais em todo o design de sua API, seguindo as melhores práticas da indústria.

Introdução

Você está projetando uma API REST. Você precisa de um endpoint para obter um usuário por ID. Você usa /user/123 ou /users/123? Essa pergunta tem gerado inúmeros debates, tópicos no Stack Overflow e discussões entre equipes.

A resposta é clara: use o plural. Mas entender o porquê importa mais do que memorizar a regra. O raciocínio se conecta a como o REST funciona, como as coleções se comportam e como os desenvolvedores pensam sobre os recursos.

A antiga Swagger Petstore errou nisso, usando /pet/{id} em vez de /pets/{id}. Essa inconsistência ensinou a milhões de desenvolvedores o padrão errado. A Modern PetstoreAPI corrige isso usando nomes plurais de forma consistente em todos os endpoints.

Neste guia, você aprenderá por que os nomes plurais são a escolha certa, como eles se alinham com os princípios REST e como implementá-los corretamente usando a Modern PetstoreAPI como referência.

O Debate Plural vs. Singular

O debate existe porque ambas as abordagens parecem lógicas à primeira vista.

O Argumento Singular

“Quando eu solicito /user/123, estou recebendo um usuário, não vários usuários. O singular faz sentido.”

Este raciocínio foca na resposta — você está obtendo um único recurso, então a URL deve ser singular.

O Argumento Plural

“A URL representa uma coleção. /users é a coleção de todos os usuários. /users/123 é o item 123 dessa coleção.”

Este raciocínio foca na estrutura do recurso — URLs representam coleções, e você está acessando itens dentro dessas coleções.

Por Que Isso Importa

Sua escolha afeta:

• Consistência da API - Nomes misturados confundem os desenvolvedores
• Modelos mentais - Como os desenvolvedores entendem a estrutura da sua API
• Geração de código - Ferramentas geram código cliente baseado nos nomes dos recursos
• Clareza da documentação - A documentação precisa explicar sua lógica de nomenclatura

Por Que Nomes Plurais Vencem

Nomes de recursos plurais se alinham com os princípios REST e a semântica HTTP. Veja o porquê.

1. Coleções São Plurais

Em REST, recursos são coleções. Quando você acessa /users, você está acessando a coleção de usuários. Quando você acessa /users/123, você está acessando o item 123 na coleção de usuários.

GET /users          ← A coleção de usuários
GET /users/123      ← Item 123 na coleção de usuários
POST /users         ← Adicionar à coleção de usuários
DELETE /users/123   ← Remover item 123 da coleção de usuários

Este modelo mental é consistente. A coleção é sempre /users, seja para acessar todos os itens ou um item.

Com nomes singulares, o modelo mental se quebra:

GET /user           ← Qual usuário?
GET /user/123       ← Isso faz sentido
POST /user          ← Adicionar a... o quê?

2. Métodos HTTP Operam em Coleções

Métodos HTTP descrevem operações em coleções:

• GET /users - Recuperar a coleção
• POST /users - Adicionar à coleção
• GET /users/123 - Recuperar o item 123 da coleção
• PUT /users/123 - Substituir o item 123 na coleção
• DELETE /users/123 - Remover o item 123 da coleção

A coleção é o recurso. Itens individuais são membros dessa coleção.

3. Consistência Entre Endpoints

Nomes plurais criam consistência:

GET /pets           ← Coleção
GET /pets/123       ← Item na coleção
GET /orders         ← Coleção
GET /orders/456     ← Item na coleção

Nomes singulares forçam você a alternar entre singular e plural:

GET /pet            ← Não faz sentido
GET /pet/123        ← Faz sentido
GET /pets           ← Espera, agora é plural?

4. Padrões da Indústria

Grandes APIs usam nomes plurais:

• GitHub API: /repos, /users, /issues
• Stripe API: /customers, /charges, /subscriptions
• Twilio API: /accounts, /messages, /calls
• Google APIs: /users, /groups, /files

A Modern PetstoreAPI segue este padrão com /pets, /orders, /users.

O Modelo Mental da Coleção

Compreender as coleções ajuda você a projetar melhores APIs.

Coleções em REST

Uma coleção é um conjunto de recursos. Em uma API de pet shop:

• /pets - A coleção de todos os animais de estimação
• /orders - A coleção de todos os pedidos
• /users - A coleção de todos os usuários

Cada coleção suporta operações:

GET /pets           ← Listar animais de estimação (com filtragem, paginação)
POST /pets          ← Criar um novo animal de estimação
GET /pets/{id}      ← Obter um animal de estimação específico
PUT /pets/{id}      ← Atualizar um animal de estimação específico
DELETE /pets/{id}   ← Excluir um animal de estimação específico

Subcoleções

As coleções podem conter subcoleções:

GET /pets/{id}/photos           ← Coleção de fotos para o animal de estimação {id}
POST /pets/{id}/photos          ← Adicionar foto ao animal de estimação {id}
GET /pets/{id}/photos/{photoId} ← Foto específica

O padrão permanece consistente: coleções são plurais, itens são acessados por ID.

Exemplo da Modern PetstoreAPI

A Modern PetstoreAPI implementa isso corretamente:

GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items

Cada coleção é plural. Cada acesso a item usa {id} dentro dessa coleção.

Como a Modern PetstoreAPI Usa Nomes Plurais

Vamos ver exemplos reais da Modern PetstoreAPI.

Recursos de Animais de Estimação

GET    /pets                    ← Listar todos os animais de estimação
POST   /pets                    ← Criar um novo animal de estimação
GET    /pets/{petId}            ← Obter animal de estimação específico
PUT    /pets/{petId}            ← Atualizar animal de estimação
DELETE /pets/{petId}            ← Excluir animal de estimação
GET    /pets?status=AVAILABLE   ← Filtrar animais de estimação por status

Recursos de Pedidos

GET    /orders                  ← Listar todos os pedidos
POST   /orders                  ← Criar pedido
GET    /orders/{orderId}        ← Obter pedido específico
PUT    /orders/{orderId}        ← Atualizar pedido
DELETE /orders/{orderId}        ← Cancelar pedido

Recursos de Usuários

GET    /users                   ← Listar usuários
POST   /users                   ← Criar usuário
GET    /users/{userId}          ← Obter usuário específico
PUT    /users/{userId}          ← Atualizar usuário
DELETE /users/{userId}          ← Excluir usuário

Recursos Aninhados

GET /pets/{petId}/photos                    ← Fotos do animal de estimação
POST /pets/{petId}/photos                   ← Adicionar foto
GET /pets/{petId}/vaccinations              ← Vacinações do animal de estimação
POST /pets/{petId}/vaccinations             ← Registrar vacinação
GET /orders/{orderId}/items                 ← Itens do pedido

Confira a documentação completa da API REST para listar todos os endpoints.

Argumentos Comuns Para o Singular (e Por Que Estão Errados)

Vamos abordar os argumentos comuns para nomes singulares.

Argumento 1: “A Resposta É Singular”

Alegação: “Quando faço GET /user/123, recebo um usuário. O singular faz sentido.”

Contra-argumento: A URL representa a localização do recurso, não a resposta. /users/123 significa “item 123 na coleção de usuários”. O fato de a resposta ser singular não altera a estrutura da coleção.

Argumento 2: “Lê Melhor no Código”

Alegação: “getUser(id) lê melhor do que getUsers(id).”

Contra-argumento: A nomenclatura do seu código cliente é independente da estrutura da URL. Você pode ter:

// URL: GET /users/123
function getUser(id) {
  return api.get(`/users/${id}`);
}

O nome da função não precisa corresponder à URL.

Argumento 3: “Singular Evita Problemas de Gramática”

Alegação: “E quanto a recursos como ‘status’ ou ‘informação’ que não possuem plurais claros?”

Contra-argumento: Estes são geralmente recursos singleton, não coleções. Use o singular para singletons:

GET /status         ← Status do sistema (singleton)
GET /configuration  ← Configuração do aplicativo (singleton)
GET /users          ← Coleção de usuários (plural)

Argumento 4: “Meu ORM Usa Nomes de Tabela Singulares”

Alegação: “Minhas tabelas de banco de dados são singulares (user, order), então minha API deve corresponder.”

Contra-argumento: O design da sua API não deve vazar detalhes de implementação do banco de dados. As APIs REST representam recursos, não tabelas de banco de dados. Use o plural para coleções, independentemente do seu esquema de banco de dados.

Testando a Nomenclatura de Recursos com Apidog

O Apidog ajuda a validar e testar as convenções de nomenclatura de recursos.

Importar a Modern PetstoreAPI

1. Importe a especificação OpenAPI da Modern PetstoreAPI
2. O Apidog detecta automaticamente os padrões de recursos
3. Revise a nomenclatura dos endpoints para consistência

Criar Testes de Convenção de Nomenclatura

// Script de teste do Apidog
pm.test("Nomes dos recursos são plurais", function() {
  const path = pm.request.url.getPath();
  const segments = path.split('/').filter(s => s);

  // Verifica se o primeiro segmento é plural
  const resource = segments[0];
  pm.expect(resource).to.match(/s$/); // Termina com 's'
});

Validar Consistência

O Apidog pode verificar:

• Todos os endpoints de coleção usam nomes plurais
• Sub-recursos seguem o mesmo padrão
• Nenhuma mistura de singular/plural na mesma API

Testar com Solicitações Reais

GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders

O Apidog valida as respostas e ajuda a garantir a consistência da nomenclatura em sua API.

Casos Limite e Exceções

Alguns recursos não se encaixam no padrão plural.

Recursos Singleton

Recursos que existem apenas uma vez devem ser singulares:

GET /status         ← Status do sistema
GET /configuration  ← Configuração do aplicativo
GET /health         ← Verificação de saúde
GET /metrics        ← Métricas do sistema

Estas não são coleções, então o plural não se aplica.

Recursos de Controlador

Ações que não se encaixam nas operações CRUD:

POST /login         ← Ação de autenticação
POST /logout        ← Término de sessão
POST /search        ← Operação de busca complexa

Estas são exceções aceitáveis porque representam ações, não recursos.

Substantivos Incontáveis

Alguns substantivos não possuem plurais claros:

GET /information    ← Singular (incontável)
GET /data           ← Singular (incontável)
GET /equipment      ← Singular (incontável)

Use o singular para substantivos incontáveis, mas estes são raros em APIs típicas.

Abordagem da Modern PetstoreAPI

A Modern PetstoreAPI lida com esses casos:

# Coleções (plural)
GET /pets
GET /orders
GET /users

# Singletons (singular)
GET /health
GET /metrics

# Ações (verbos singulares)
POST /login
POST /logout

Conclusão

Os nomes dos recursos da API REST devem ser plurais. Isso se alinha com a semântica de coleção, os métodos HTTP e os padrões da indústria. A Modern PetstoreAPI demonstra esse padrão corretamente em todos os endpoints.

Principais aprendizados:

• Use nomes plurais para coleções (/pets, /orders, /users)
• Itens individuais são acessados dentro de coleções (/pets/123)
• Recursos singleton podem ser singulares (/status, /health)
• A consistência importa mais do que a perfeição
• Teste suas convenções de nomenclatura com o Apidog

O debate plural vs. singular está resolvido. Siga o padrão da indústria, use nomes plurais e construa APIs que os desenvolvedores entendam intuitivamente.

Próximos passos:

1. Revise seus endpoints de API para consistência de nomenclatura
2. Verifique a documentação da Modern PetstoreAPI para padrões de referência
3. Use o Apidog para validar o design da sua API
4. Atualize sua especificação OpenAPI com nomes de recursos plurais

FAQ

Devo mudar minha API existente de singular para plural?

Se sua API já está em produção, mudar os nomes dos recursos é uma alteração que pode quebrar a compatibilidade. Considere:

• Adicionar novos endpoints v2 com nomes plurais
• Manter a compatibilidade retroativa com redirecionamentos
• Documentar claramente a convenção de nomenclatura

Não quebre clientes existentes apenas pela consistência da nomenclatura.

E os recursos que já são plurais?

Se o nome do recurso já é naturalmente plural (como “analytics” ou “series”), mantenha-o como está:

GET /analytics      ← Já plural
GET /series         ← Já plural
GET /species        ← Já plural

Como lidar com recursos aninhados?

Mantenha ambos os níveis no plural:

GET /users/{userId}/orders              ← Ambos plurais
GET /pets/{petId}/vaccinations          ← Ambos plurais
GET /orders/{orderId}/items             ← Ambos plurais

E se minha equipe preferir o singular?

A consistência dentro da sua API é o mais importante. Se sua equipe já padronizou nomes singulares e a mudança causaria confusão, mantenha o singular. Mas para novas APIs, use o plural.

O GraphQL usa plural ou singular?

O GraphQL geralmente usa singular para consultas de item único e plural para listas:

query {
  user(id: "123") { ... }      # Singular
  users(limit: 10) { ... }     # Plural
}

Isso é diferente do REST porque as consultas GraphQL são explícitas sobre retornar um ou muitos.

Como a Modern PetstoreAPI lida com isso?

A Modern PetstoreAPI usa nomes plurais de forma consistente em todos os endpoints REST. Verifique o guia da API REST para exemplos completos.

Posso testar as convenções de nomenclatura automaticamente?

Sim, o Apidog pode executar testes automatizados para verificar os padrões de nomenclatura de recursos em toda a sua API. Importe sua especificação OpenAPI e crie casos de teste para convenções de nomenclatura.

E as APIs não-inglesas?

A regra do plural se aplica independentemente do idioma. Se sua API usa nomes de recursos em francês, use plurais em francês. Se usa japonês, siga as regras gramaticais japonesas. O princípio (coleções são plurais) permanece o mesmo.