Por que Não Usar Verbos em URLs de API REST?

Resumo

As URLs de APIs REST devem conter substantivos (recursos), não verbos (ações). Os métodos HTTP (GET, POST, PUT, DELETE) são os verbos. Usar verbos de ação como /getUser ou /createOrder viola os princípios REST, cria inconsistência e torna as APIs mais difíceis de manter. A Modern PetstoreAPI usa URLs orientadas a recursos em toda a sua extensão.

Introdução

Você está projetando um endpoint de API para buscar pets por status. Seu primeiro instinto pode ser: GET /findPetsByStatus?status=available. É descritivo, claro e diz exatamente o que faz. Também está errado.

APIs REST devem usar substantivos nas URLs, não verbos. O método HTTP é o verbo. GET /pets?status=available é o design correto. A URL representa o recurso (pets), e o método representa a ação (obter).

A antiga Swagger Petstore cometeu esse erro com endpoints como /pet/findByStatus e /pet/findByTags. Esses verbos de ação nas URLs violam os princípios REST e criam problemas de manutenção. A Modern PetstoreAPI corrige isso usando URLs orientadas a recursos de forma consistente.

Neste guia, você aprenderá por que os verbos não pertencem às URLs REST, como projetar endpoints orientados a recursos e como a Modern PetstoreAPI implementa isso corretamente.

O Problema dos Verbos em APIs REST

Verbos de ação nas URLs indicam que você está pensando em termos de RPC (Remote Procedure Call), não em termos de REST.

URLs Estilo RPC (Errado)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

Essas URLs descrevem ações. Elas se parecem com chamadas de função: createUser(), getUser(), sendEmail().

URLs Estilo REST (Correto)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

Essas URLs descrevem recursos. O método HTTP fornece a ação.

Por Que Isso Importa

Consistência: URLs REST seguem um padrão previsível. Uma vez que você sabe o nome do recurso, você conhece todos os endpoints:

• GET /pets - Listar pets
• POST /pets - Criar pet
• GET /pets/{id} - Obter pet
• PUT /pets/{id} - Atualizar pet
• DELETE /pets/{id} - Excluir pet

Com URLs baseadas em verbos, cada endpoint é único. Não há um padrão a seguir.

Escalabilidade: À medida que sua API cresce, URLs baseadas em verbos se multiplicam:

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

URLs orientadas a recursos usam parâmetros de consulta:

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

Um endpoint gerencia toda a filtragem.

Por Que os Métodos HTTP São os Verbos

REST alavanca os verbos incorporados do HTTP. Você não precisa inventar os seus próprios.

Métodos HTTP Mapeiam para Operações CRUD

POST   → Criar
GET    → Ler
PUT    → Atualizar (substituir)
PATCH  → Atualizar (parcial)
DELETE → Excluir

Esses métodos têm semânticas definidas. GET é seguro e idempotente. POST cria recursos. DELETE os remove.

Exemplo: Gerenciamento de Usuários

Errado (verbos nas URLs):

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

Cada operação usa uma URL diferente. O método HTTP não transmite significado.

Correto (métodos HTTP como verbos):

POST /users           ← Criar usuário
GET /users/123        ← Obter usuário
PUT /users/123        ← Atualizar usuário
DELETE /users/123     ← Excluir usuário

A URL permanece a mesma. O método muda.

Benefícios do Uso de Métodos HTTP

1. Cache: Requisições GET podem ser armazenadas em cache. Navegadores e proxies sabem disso. Se você usar POST /getUser, o cache é quebrado.

2. Idempotência: PUT e DELETE são idempotentes. Chamá-los várias vezes tem o mesmo efeito que chamá-los uma vez. Isso é importante para a lógica de repetição.

3. Segurança: GET é seguro — não modifica o estado. Ferramentas e rastreadores podem chamar endpoints GET com segurança.

4. Conformidade com Padrões: Clientes HTTP, proxies e caches entendem os métodos HTTP. Eles não entendem seus verbos personalizados.

Exemplos Reais da Swagger Petstore

A antiga Swagger Petstore inclui vários endpoints baseados em verbos.

Exemplo 1: Encontrando Pets por Status

Swagger Petstore (Errado):

GET /pet/findByStatus?status=available

Problemas:

• findByStatus é uma frase verbal
• Inconsistente com o endpoint /pet/{id}
• Não pode ser estendido facilmente (e quanto a encontrar por outros critérios?)

Modern PetstoreAPI (Correto):

GET /pets?status=AVAILABLE

Benefícios:

• Orientado a recursos (/pets)
• Usa parâmetros de consulta para filtragem
• Consistente com outros endpoints
• Fácil de estender: GET /pets?status=AVAILABLE&species=dog

Veja a documentação REST da Modern PetstoreAPI para a implementação completa.

Exemplo 2: Encontrando Pets por Tags

Swagger Petstore (Errado):

GET /pet/findByTags?tags=tag1,tag2

Modern PetstoreAPI (Correto):

GET /pets?tags=friendly,trained

Exemplo 3: Login de Usuário

Swagger Petstore (Errado):

GET /user/login?username=john&password=secret

Múltiplos problemas:

• login é um verbo
• Usando GET para autenticação (desastre de segurança)
• Senhas em parâmetros de consulta da URL

Modern PetstoreAPI (Correto):

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

Benefícios:

• Orientado a recursos (/auth)
• Método HTTP correto (POST)
• Credenciais no corpo da requisição, não na URL
• Retorna token JWT para requisições subsequentes

Como a Modern PetstoreAPI Corrige Isso

A Modern PetstoreAPI usa URLs orientadas a recursos em toda a sua extensão.

Gerenciamento de Pets

GET /pets                    ← Listar todos os pets
GET /pets?status=AVAILABLE   ← Filtrar por status
GET /pets?species=dog        ← Filtrar por espécie
GET /pets/{id}               ← Obter pet específico
POST /pets                   ← Criar novo pet
PUT /pets/{id}               ← Atualizar pet
PATCH /pets/{id}             ← Atualização parcial
DELETE /pets/{id}            ← Excluir pet

Sem verbos. Apenas recursos e métodos HTTP.

Gerenciamento de Pedidos

GET /orders                  ← Listar pedidos
GET /orders/{id}             ← Obter pedido
POST /orders                 ← Criar pedido
PUT /orders/{id}             ← Atualizar pedido
DELETE /orders/{id}          ← Cancelar pedido
GET /orders/{id}/items       ← Obter itens do pedido

Operações Complexas

Para operações que não se encaixam perfeitamente no modelo CRUD, a Modern PetstoreAPI usa sub-recursos:

POST /orders/{id}/payment    ← Processar pagamento para pedido
POST /orders/{id}/shipment   ← Criar envio para pedido
POST /pets/{id}/adoption     ← Iniciar processo de adoção

Estes ainda são orientados a recursos. /orders/{id}/payment representa o recurso de pagamento para um pedido.

Quando Verbos Parecem Necessários

Algumas operações não se encaixam no modelo CRUD. Veja como lidar com elas sem verbos nas URLs.

Operações de Busca

Errado:

GET /searchPets?query=labrador

Opção Correta 1 (Parâmetros de Consulta):

GET /pets?search=labrador

Opção Correta 2 (Recurso de Busca):

GET /pets/search?q=labrador

Opção Correta 3 (Método QUERY):

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

A Modern PetstoreAPI suporta todos os três padrões dependendo da complexidade.

Cálculos

Errado:

GET /calculateShipping?weight=10&destination=NY

Correto:

GET /shipping-estimates?weight=10&destination=NY

O recurso é "estimativas de frete", não a ação de cálculo.

Operações em Lote

Errado:

POST /batchDeletePets

Correto:

DELETE /pets?ids=1,2,3

Ou use um recurso de lote:

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

Ações Que Alteram o Estado

Errado:

POST /activateUser
POST /deactivateUser

Correto:

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

As mudanças de estado são atualizações no recurso.

Testando o Design de URL com Apidog

O Apidog ajuda você a validar o design da API REST e a detectar o uso de verbos em URLs.

Importar Modern PetstoreAPI

1. Importe a especificação OpenAPI da Modern PetstoreAPI
2. O Apidog gera automaticamente casos de teste
3. Revise a estrutura e a nomeação dos endpoints

Verificar Verbos em URLs

Crie uma regra de validação personalizada no Apidog:

// Verifica se a URL contém verbos de ação comuns
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL contém verbo: ${verb}. Use URLs orientadas a recursos.`);
  }
}

Testar a Consistência do Endpoint

O Apidog pode verificar se os endpoints relacionados seguem padrões consistentes:

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

Todos usam o mesmo recurso base (/pets).

Comparar com a Modern PetstoreAPI

Use a Modern PetstoreAPI como referência:

1. Importe tanto sua API quanto a Modern PetstoreAPI no Apidog
2. Compare as estruturas dos endpoints lado a lado
3. Identifique inconsistências e uso de verbos
4. Refatore sua API para corresponder aos princípios REST

Estratégias de Migração

Se você tem uma API existente com verbos em URLs, veja como migrar.

Estratégia 1: Versionamento

Crie uma nova versão da API com URLs corretas:

# API Antiga (v1)
GET /api/v1/findPetsByStatus?status=available

# Nova API (v2)
GET /api/v2/pets?status=available

Mantenha a v1 para compatibilidade retroativa, incentive a migração para a v2.

Estratégia 2: Alias

Suporte URLs antigas e novas temporariamente:

# URL Antiga (depreciada)
GET /pet/findByStatus?status=available

# Nova URL (preferencial)
GET /pets?status=available

Retorne avisos de depreciação nas respostas:

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "Este endpoint está depreciado. Use GET /pets?status=available.",
      "sunset": "2027-01-01"
    }
  ]
}

Estratégia 3: Redirecionamentos

Use redirecionamentos HTTP 301 para migrações simples:

GET /pet/findByStatus?status=available
→ 301 Moved Permanently
Location: /pets?status=available

Isso funciona para requisições GET, mas não para POST, PUT ou DELETE.

Conclusão

As URLs de APIs REST devem conter substantivos (recursos), não verbos (ações). Os métodos HTTP fornecem os verbos. Este princípio cria APIs consistentes, escaláveis e de fácil manutenção.

A antiga Swagger Petstore violava isso com endpoints como /pet/findByStatus. A Modern PetstoreAPI corrige isso usando URLs orientadas a recursos em toda a sua extensão: /pets?status=AVAILABLE.

Principais aprendizados:

• Use substantivos nas URLs: /pets, /orders, /users
• Deixe os métodos HTTP serem os verbos: GET, POST, PUT, DELETE
• Use parâmetros de consulta para filtragem: /pets?status=available
• Para operações complexas, use sub-recursos: /orders/{id}/payment
• Teste o design da sua API com o Apidog para detectar o uso de verbos precocemente

Confira a documentação da Modern PetstoreAPI para exemplos completos de design de URL orientado a recursos.

FAQ

Posso usar verbos em URLs REST?

Raramente. Se uma operação realmente não se encaixa no modelo de recurso (como /search ou /login), um verbo pode ser aceitável. Mas 95% das vezes, você pode modelá-lo como um recurso.

E quanto a /login e /logout?

Estas são exceções comuns. Muitas APIs usam /auth/login e /auth/logout. Alternativamente, modele-os como recursos: POST /sessions (login) e DELETE /sessions/{id} (logout).

Como lidar com consultas complexas?

Use parâmetros de consulta para filtragem simples: /pets?status=available&species=dog. Para consultas complexas, use o método HTTP QUERY ou um recurso de busca: POST /pets/search.

E se minha operação não mapear para CRUD?

Modele-a como um sub-recurso. Em vez de POST /processPayment, use POST /orders/{id}/payment. O pagamento é um recurso relacionado ao pedido.

Como testar se minhas URLs são orientadas a recursos?

Use o Apidog para importar sua especificação OpenAPI e verificar verbos em URLs. Compare a estrutura da sua API com a Modern PetstoreAPI como referência.

Devo usar /pets/search ou /pets?search=query?

Ambos são aceitáveis. /pets?search=query é mais simples para buscas básicas. /pets/search ou QUERY /pets funciona melhor para buscas complexas com múltiplos parâmetros.

Como migrar de URLs baseadas em verbos?

Use o versionamento da API (/v2/pets em vez de /v1/findPets), adicione avisos de depreciação e dê tempo para os clientes migrarem. Consulte a seção Estratégias de Migração para detalhes.

A Modern PetstoreAPI usa algum verbo em URLs?

A Modern PetstoreAPI evita verbos em URLs. Operações como busca, filtro e autenticação são modeladas como recursos ou usam parâmetros de consulta. Verifique a documentação da API REST para exemplos.