O que é endpoint de API e como ele é estruturado

Um endpoint não é só uma URL. Duas requisições para o mesmo endereço, https://api.loja.com.br/pedidos, podem fazer coisas completamente diferentes: uma lista os pedidos, a outra cria um pedido novo. O que muda é o método HTTP. Por isso quem trabalha com APIs fala em “o endpoint GET /pedidos” e “o endpoint POST /pedidos“, como se fossem duas portas distintas no mesmo corredor.

Resumo rápido: endpoint é o ponto de acesso de uma API, formado pela combinação de um método HTTP (GET, POST, PUT, PATCH, DELETE) com um caminho (/pedidos/123). Cada combinação executa uma operação específica e devolve uma resposta, normalmente em JSON, com um código de status.

As dúvidas abaixo são as que mais aparecem quando alguém começa a consumir ou a construir APIs.

Quais são as partes de um endpoint na URL?

Pegue este exemplo e desmonte peça por peça:

GET https://api.loja.com.br/v1/clientes/58/pedidos?status=pago&pagina=2

Um jeito simples de lembrar: o caminho diz “o quê”, a query string diz “quais e quantos” e o método diz “o que fazer com isso”.

Endpoint, rota e API são a mesma coisa?

Não, embora muita gente use os termos como sinônimos. A API é o conjunto inteiro, o contrato que um sistema oferece a outros. O endpoint é cada operação disponível nesse contrato. A rota é o nome que os frameworks do lado do servidor (Express, Flask, Laravel, Spring) dão ao código que responde a um endpoint.

# Flask: a rota que atende o endpoint GET /produtos/<id>
@app.get("/produtos/<int:produto_id>")
def detalhar_produto(produto_id):
    produto = buscar_no_banco(produto_id)
    if produto is None:
        return {"erro": "produto não encontrado"}, 404
    return produto, 200

Quem consome a API enxerga o endpoint. Quem programa o servidor escreve a rota. É a mesma porta vista de lados opostos.

Qual método HTTP usar em cada endpoint?

A semântica dos métodos está definida na especificação do HTTP, a RFC 9110, que padroniza a semântica do HTTP. Para o dia a dia, esta tabela resolve a maior parte das decisões:

A última coluna é a tal idempotência, e ela tem consequência prática: se a rede cair no meio de um PUT, o cliente pode reenviar sem medo. Num POST de pagamento, reenviar pode cobrar duas vezes, e é por isso que APIs de pagamento costumam pedir uma chave de idempotência no cabeçalho.

Como nomear endpoints de um jeito que outros devs entendam?

Não existe lei, mas existe convenção, e seguir a convenção poupa documentação. As regras que mais aparecem nas APIs bem feitas:

• Substantivos, não verbos. POST /clientes, e não POST /criarCliente. O verbo já está no método.
• Plural para coleções. /produtos e /produtos/7, mantendo o mesmo nome nos dois.
• Letras minúsculas e hífen. /notas-fiscais lê melhor que /NotasFiscais ou /notas_fiscais na URL.
• Hierarquia só quando há dono. /clientes/58/pedidos faz sentido; aninhar três ou quatro níveis deixa a URL frágil.
• Filtros na query string. /pedidos?status=pago, e não /pedidos/pagos.
• Versão na URL ou no cabeçalho, escolhida uma vez e mantida.

Ações que não se encaixam em CRUD, como cancelar um pedido, costumam virar um sub-recurso: POST /pedidos/123/cancelamento. Fica explícito e ainda deixa espaço para guardar quem cancelou e quando.

O que um endpoint devolve quando dá certo ou errado?

Toda resposta traz um código de status de três dígitos. A tabela completa está na página da MDN sobre códigos de status de respostas HTTP, mas um punhado deles cobre quase tudo:

• 200 OK: deu certo e tem conteúdo na resposta.
• 201 Created: o POST criou o recurso.
• 204 No Content: deu certo e não há nada a devolver, comum em DELETE.
• 400 Bad Request: o cliente mandou dados inválidos.
• 401 e 403: falta autenticação (401) ou falta permissão (403).
• 404 Not Found: o recurso não existe.
• 500: erro no servidor, culpa de quem mantém a API.

Um erro clássico de API iniciante é devolver 200 com {"sucesso": false} no corpo. Quem consome precisa ler o JSON para descobrir que falhou, e ferramentas de monitoramento contam a falha como sucesso.

Como testar um endpoint sem escrever código?

Para GET, o próprio navegador serve: cole a URL na barra de endereço. Para os demais métodos, o curl no terminal resolve:

curl -X POST https://api.exemplo.com.br/v1/pedidos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -d '{"produto_id": 7, "quantidade": 2}'

Clientes gráficos como Insomnia, Postman ou a extensão REST Client do VS Code fazem o mesmo com formulários e histórico. E, no navegador, a aba Network das ferramentas de desenvolvedor mostra todos os endpoints que um site chama enquanto você navega, um ótimo jeito de aprender olhando APIs reais.

Por que tantas APIs colocam /v1 no endpoint?

Porque endpoints são contratos, e contratos têm clientes que você não controla. Se um app de celular instalado em 50 mil aparelhos espera o campo preco e você o renomeia para valor, todos esses apps quebram até o usuário atualizar, o que pode levar meses.

A versão no caminho resolve isso: o /v1/produtos continua respondendo como sempre, e o formato novo vai para /v2/produtos. Os clientes migram no ritmo deles e a versão antiga é desligada com aviso prévio. Mudanças que só acrescentam campos ou endpoints novos normalmente não exigem versão nova, porque quem já usa a API simplesmente ignora o que não conhece. Remover, renomear ou mudar o tipo de um campo, sim.

Uma prática que ajuda é padronizar também o corpo das respostas de erro. Em vez de cada endpoint inventar seu formato, a RFC 9457, sobre detalhes de problemas em APIs HTTP propõe um JSON com campos como type, title, status e detail, que muitos frameworks já geram sozinhos.

Endpoint público precisa de autenticação?

Quase sempre sim, nem que seja uma chave simples para controlar uso. Endpoints que leem dados públicos (cotação, CEP) às vezes são abertos, mas qualquer endpoint que grava, apaga ou expõe dado pessoal precisa saber quem está chamando. O mais comum hoje é um token no cabeçalho Authorization.

Também vale pensar em quem vai chamar seu endpoint e com que frequência. Se a ideia é avisar outro sistema quando algo acontece, às vezes o desenho certo nem é um endpoint consultado de minuto em minuto, e o artigo sobre trocar a consulta periódica por webhook mostra a alternativa.

Para colocar a mão na massa, o próximo passo prático é subir sua primeira API pequena, com três ou quatro endpoints bem nomeados, e testar cada um com curl. O guia de como criar uma API REST simples em Python serve de roteiro, e os termos que aparecerem pelo caminho estão no glossário de programação.