ForHosting KIT · Monitorar sites

Verificador de nomes de endpoints REST

Cole um caminho como /users/{id}/orders e veja quais regras de nomes ele cumpre: minúsculas, palavras separadas por hífen, substantivos no plural e nenhum verbo. Cada regra quebrada aparece por segmento, e o comentário de revisão vira correção. Grátis no seu navegador.

Grátis
Funciona no seu navegador
Sem cadastro
Seus dados não saem do seu aparelho

Executar grátis Ver a API

Use pelo WebAPIE-mailTelegramApp em breve

Exemplo resolvido

Se você digitar

Caminho: /v1/users/{id}/orders

Você obtém

Segmentos: 4

Você envia um caminho e recebe um veredito estruturado: quais convenções passaram, quais falharam e um problema legível para cada segmento infrator, transformando um comentário de revisão em correção, não em debate.

Como é um caminho bem nomeado

A convenção amplamente aceita é que cada segmento do caminho seja um substantivo e que as coleções usem o plural: /users para a coleção, /users/{id} para um membro dela. As palavras dentro de um segmento são separadas por hífens, o estilo kebab-case, porque underscores são mais difíceis de ler em URLs e podem desaparecer sob o sublinhado de links, enquanto o camelCase mistura maiúsculas num lugar onde o padrão é minúsculo. Prefixos de versão como v1 ou v2 são prática aceita e não são tratados como erros de nomenclatura.

O que este verificador testa e como ele decide

O verificador divide seu caminho nas barras e ignora a query string e o fragmento, pois eles não fazem parte da nomenclatura do recurso. Cada segmento restante é testado contra quatro regras, e cada falha é relatada separadamente para que você veja exatamente qual convenção um segmento viola. Primeiro, minúsculas: qualquer letra maiúscula num segmento é sinalizada, pois maiúsculas em caminhos são uma fonte comum de bugs de roteamento em servidores sensíveis a maiúsculas.

Segundo, hifenização: underscores e espaços dentro de um segmento são sinalizados, com hífens indicados como substitutos. Terceiro, substantivos no plural: segmentos que não são prefixos de versão nem parâmetros de caminho devem terminar numa palavra com aparência de plural; um segmento como /user é sinalizado enquanto /users passa, e segmentos compostos como /user-profiles são julgados pela última palavra. Quarto, verbos: cada palavra separada por hífen é comparada a uma lista fixa de verbos comuns em inglês como get, create, update, delete, fetch e login, e qualquer correspondência é sinalizada.

Parâmetros de caminho nas formas {id} ou :id são isentos das regras de substantivo e verbo, pois o nome de um parâmetro segue convenções diferentes das de um recurso estático.

Casos de uso

Encerrar debates de estilo na revisão de design

Substitua opinião por uma lista concreta de violações quando dois revisores discordam sobre como um caminho deveria ser.

Perguntas frequentes

Quanto custa?

Também é grátis rodar no seu navegador nesta página.

Como ele decide se uma palavra está no plural?

Com uma heurística simples e determinística: a última palavra separada por hífen de um segmento deve terminar em 's'. Segmentos de versão como v1 e parâmetros de caminho como {id} ou :id são isentos.

Ele verifica query strings ou fragmentos?

Não. Tudo depois de '?' ou '#' é removido antes das verificações, pois parâmetros de query e fragmentos não fazem parte da nomenclatura do recurso.

Qual lista de verbos ele usa?

Uma lista fixa de verbos comuns em inglês vistos em APIs reais — get, create, update, delete, fetch, find, search, add, remove, login, register e similares. A lista é determinística e não muda entre chamadas.

Por que hífens e não sublinhados nem camelCase?

Sublinhados são mais difíceis de ler num endereço web e podem sumir sob o sublinhado de um link, e o camelCase mistura maiúsculas onde o normal são minúsculas. Por isso sublinhados e espaços são apontados, com o hífen como correção.

Ferramentas relacionadas

Para desenvolvedores — acesso via API

Tudo nesta página está disponível via API. Esta seção é para equipes que querem integrar a ferramenta aos próprios sistemas; quem não precisa disso pode simplesmente usar a ferramenta acima.

Endpoint

POSThttps://api.kit.forhosting.com/dev/rest-endpoint-naming-check

Autenticação por token Bearer. Um único POST coloca a tarefa na fila; o resultado chega por webhook ou link assinado.

Chame do seu código

curl -X POST https://api.kit.forhosting.com/dev/rest-endpoint-naming-check \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/api/v1/user-profiles"}'

const res = await fetch("https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "path": "/api/v1/user-profiles"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/dev/rest-endpoint-naming-check",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "path": "/api/v1/user-profiles"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"path":"/api/v1/user-profiles"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"path":"/api/v1/user-profiles"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/rest-endpoint-naming-check", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

Exemplo de requisição

{
  "path": "/api/v1/user-profiles"
}

Exemplo de resposta

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "dev.rest_endpoint_naming_check",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

A API é assíncrona: cada chamada devolve um task_id na hora. Se preferir polling, consulte o status a até 1 requisição por segundo.

Preço

por chamadaUS$ 0,002

Preço publicado, sem tokens nem créditos escondidos. Tarefa que falha não é cobrada.

Limites

max_chars 2048

Erros

HTTP	Código	O que significa
`401`	`unauthorized`	Token ausente ou inválido. Confira o header Authorization.
`402`	`insufficient_balance`	Saldo insuficiente para esta tarefa. Faça uma recarga e tente de novo.
`404`	`unknown_type`	Esse tipo de tarefa não existe. Confira o campo type no catálogo.
`429`	`rate_limited`	Muitas requisições em pouco tempo. Espere um instante e tente de novo.

Notas técnicas

O verificador de nomenclatura de endpoints REST recebe um caminho como /users/{id}/orders e testa cada segmento contra as convenções em que a maioria dos guias de estilo concorda: segmentos em letras minúsculas, palavras separadas por hífens em vez de underscores ou camelCase, recursos de coleção como substantivos no plural e verbos fora do caminho, pois o método HTTP já nomeia a ação.

Como é um bom caminho REST

Caminhos REST nomeiam recursos, não ações. A ação já está no método HTTP — GET, POST, PUT, DELETE — então um caminho como /getUsers diz a mesma coisa duas vezes e de forma inconsistente com o resto da API. Quando um caminho segue essas regras, ele se torna previsível: um desenvolvedor que conhece um endpoint consegue adivinhar o resto da superfície sem ler a documentação, e ferramentas como roteadores, gateways e linters podem ser configuradas uma vez e reutilizadas em todos os serviços que a equipe entrega.

Usando o veredito em revisões e pipelines

A saída foi projetada para ser consumida por máquinas e também legível. Um fluxo típico é rodar o verificador sobre cada nova rota que um serviço adiciona: cole o caminho durante a revisão de design, capture o desvio antes de a rota ir ao ar e evite a escolha dolorosa entre manter um caminho feio para sempre ou quebrar clientes com uma renomeação. Além da lista de problemas em linguagem simples, você recebe um objeto checks com um booleano por convenção — lowercase, hyphenated, plural_nouns e no_verbs — mais um sinalizador valid geral, para que um job de CI possa reprovar um pull request com uma única condição em vez de interpretar frases. As equipes também o usam em auditorias de API, alimentando-o com rotas de um documento OpenAPI e coletando os segmentos que precisam de atenção. O mesmo código que alimenta a API roda grátis no seu navegador nesta página, então você pode testar caminhos interativamente enquanto projeta e só gastar os US$ 0,002 por requisição quando automatizar a verificação num pipeline, num linter ou num portal interno de desenvolvedores.

Casos de integração

Bloquear novas rotas no CI

Reprove um pull request quando um endpoint recém-adicionado introduz verbos, underscores ou letras maiúsculas no caminho.

Auditar a superfície de uma API existente

Passe as rotas de um documento OpenAPI pelo verificador e colete os segmentos que violam seu guia de estilo.

Perguntas técnicas

Por que verbos não são permitidos num caminho REST?

Porque o método HTTP já nomeia a ação. Um caminho como /getUsers duplica o GET e fica fora de sincronia com o resto da API; /users com o método GET diz a mesma coisa de forma consistente.

O que acontece se eu enviar um caminho vazio?

A requisição falha com um erro invalid_input explicando que um caminho não vazio é obrigatório. Entrada vazia nunca é cobrada.

Ver a documentação completa do KIT →

Executar grátis