--- term: 'Endpoint de API' seoTitle: 'O que é um Endpoint de API? Anatomia, Exemplos e Boas Práticas' headline: 'O que é um endpoint de API?' slug: endpoint-de-api category: api-realtime shortDefinition: 'Um endpoint de API é a URL específica onde uma API recebe requisições para um recurso — combinado com um método HTTP, define uma operação.' relatedTerms: - api - rest-api - api-gateway-architecture - auto-generated-database-apis contrastsWith: - api-gateway-architecture aboutTerms: - 'URL Base' - 'Parâmetros de Path' - 'Parâmetros de Query' faq: - question: 'O que é um endpoint de API, em termos simples?' answer: 'A URL específica onde uma API recebe requisições sobre um recurso — cada endpoint é uma porta de entrada da API. Uma requisição a /users/42 com o método GET pede os dados do usuário 42; o mesmo path com DELETE pede a remoção. A API é o prédio inteiro; os endpoints são suas portas endereçáveis.' - question: 'Qual é um exemplo de endpoint de API?' answer: 'https://api.example.com/v1/users/42 — uma URL base (esquema, host e versão) seguida de um path que nomeia o recurso. Equivalentes do mundo real: o endpoint /repos/OWNER/REPO de uma plataforma de hospedagem de código, ou o endpoint /classes/Todo que um app do Back4app gera automaticamente para uma classe de dados Todo.' - question: 'Qual é a diferença entre uma API e um endpoint?' answer: 'A API é o contrato inteiro — o conjunto completo de regras, recursos e operações que um serviço expõe. Um endpoint é um ponto de acesso específico dentro dela. Uma API expõe muitos endpoints, e a documentação de uma API é, em grande parte, um catálogo deles.' - question: 'Endpoint é a mesma coisa que URL?' answer: 'Não exatamente. O endpoint é expresso como uma URL, mas a URL é apenas o endereço; o endpoint é o ponto de interação que ela identifica. A documentação costuma escrever endpoints como paths com a URL base implícita — e, a rigor, o método HTTP faz parte do que define a operação naquele endereço.' - question: 'A mesma URL pode ser mais de um endpoint?' answer: 'Sim. GET /users/42 e DELETE /users/42 compartilham a URL, mas são operações diferentes — e é por isso que o padrão OpenAPI modela uma API como paths, cada um contendo múltiplas operações indexadas por método. Quando alguém conta "endpoints", normalmente está contando operações.' - question: 'Qual é a diferença entre endpoint e rota?' answer: 'Perspectiva. A rota é a definição do lado do servidor — um padrão de path, um método e uma função handler no seu framework. O endpoint é a URL voltada ao cliente onde aquela rota está acessível. A mesma coisa, vista das duas pontas opostas da requisição.' - question: 'Como descubro os endpoints de uma API?' answer: 'Três caminhos, em ordem de confiabilidade: ler a documentação ou a especificação OpenAPI legível por máquina, que enumera cada path e operação; observar o tráfego real na aba de rede das ferramentas de desenvolvedor do navegador, filtrada por fetch/XHR; ou exercitar chamadas com curl e um cliente de API para confirmar o comportamento.' - question: 'Como proteger um endpoint de API?' answer: 'Trate cada endpoint como superfície de ataque: somente HTTPS, autenticação em toda rota, autorização com privilégio mínimo, validação de entrada, rate limits, paginação com limites e mensagens de erro que não vazam detalhes internos. Depois, mantenha um inventário — endpoints "zumbis" esquecidos estão entre as principais falhas de segurança de API.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'RFC 3986 — URI: Generic Syntax' url: 'https://datatracker.ietf.org/doc/html/rfc3986' - name: 'RFC 9110 — HTTP Semantics' url: 'https://www.rfc-editor.org/rfc/rfc9110' - name: 'OpenAPI Specification — Paths and Operations' url: 'https://spec.openapis.org/oas/latest.html#paths-object' - name: 'OWASP API Security Top 10' url: 'https://owasp.org/API-Security/' cta: title: 'Endpoints que você nunca precisou projetar' text: 'Crie uma classe no Back4app e seus endpoints REST existem imediatamente — URLs de recurso, métodos, auth e permissões por conta da plataforma, consistentes em todo o seu modelo de dados.' linkText: 'Comece grátis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-08-21' translationKey: api-endpoint --- **Um endpoint de API é a URL específica onde uma API recebe requisições para um recurso — combinado com um método HTTP, define uma operação.** Essa segunda cláusula é a parte que a maioria das definições pula, e é ela que resolve a confusão clássica: `GET /users/42` e `DELETE /users/42` compartilham um endereço, mas são endpoints diferentes — do mesmo jeito que uma porta se comporta de formas distintas dependendo de você bater ou girar a chave. ## Principais pontos | Pergunta | Resposta | | --- | --- | | A fórmula | URL base + path (+ método) = uma operação sobre um recurso | | vs. a API | API = o contrato inteiro · endpoint = um ponto de acesso dentro dela | | Path vs. query | O path identifica *qual* recurso · a query diz *como* retorná-lo | | Nomenclatura | Substantivos no plural, minúsculas, aninhamento raso — o verbo é o método | | Segurança | Todo endpoint é superfície de ataque — inclusive os esquecidos | ## Anatomia da URL de um endpoint de API Cada pedaço de uma URL de requisição real, rotulado — conforme a gramática da [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986): ```text GET https://api.example.com/v1/users/42/posts?status=published&limit=20 GET método — a ação; parte da identidade da operação https esquema — TLS, inegociável api.example.com host ┐ a URL base, compartilhada por /v1 versão ┘ todos os endpoints da API /users/42/posts path — o recurso: posts do usuário 42 42 parâmetro de path — identifica QUAL recurso ?status=published parâmetros de query — COMO retorná-lo: &limit=20 filtrar, ordenar, paginar (fora da identidade) ``` Chamando um endpoint a partir do código da aplicação — o SDK compõe URL, método e auth por você: **JavaScript:** ```javascript // JavaScript / Node.js — Back4app JS SDK // Every class gets endpoints automatically — this call hits one const query = new Parse.Query('Todo'); query.equalTo('done', false); query.limit(10); const todos = await query.find(); // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Flutter:** ```dart // Flutter / Dart — Back4app Flutter SDK // Every class gets endpoints automatically — this call hits one final query = QueryBuilder(ParseObject('Todo')) ..whereEqualTo('done', false) ..setLimit(10); final response = await query.query(); // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Swift:** ```swift // iOS / Swift — Back4app Swift SDK // Every class gets endpoints automatically — this call hits one let query = Todo.query("done" == false) .limit(10) let todos = try await query.find() // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` **Kotlin:** ```kotlin // Android / Kotlin — Back4app Android SDK // Every class gets endpoints automatically — this call hits one val query = ParseQuery.getQuery("Todo") query.whereEqualTo("done", false) query.limit = 10 val todos = query.find() // Endpoint used: GET /classes/Todo?where={"done":false}&limit=10 ``` ## Endpoint vs. API vs. URL vs. rota A desambiguação de quatro vias que nenhuma página de ranking oferece sozinha: | Termo | O que é | Vocabulário de quem | | --- | --- | --- | | API | O contrato inteiro: todos os recursos, operações e regras | De todo mundo | | Endpoint | Um ponto de acesso — uma URL (+ método) que recebe requisições para um recurso | A visão de quem consome | | URL | A string de endereço que localiza o endpoint ([RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)) | A visão do fio | | Rota | A definição server-side: padrão de path + método + código do handler | A visão de quem implementa | Endpoint e rota são a mesma coisa vista de pontas opostas: o framework declara uma rota, o cliente chama um endpoint. E a [OpenAPI Specification](https://spec.openapis.org/oas/latest.html#paths-object) formaliza o quadro inteiro — uma API é um conjunto de *paths*, cada path contém *operações* indexadas por método, e "quantos endpoints essa API tem?" é, na verdade, uma contagem de operações. ```mermaid flowchart LR accTitle: Como uma requisição chega a um recurso através de um endpoint accDescr: Uma requisição do cliente com método e URL chega à URL base da API, é casada com a rota de um endpoint por path e método, passa por autenticação e validação, e o handler opera sobre o recurso subjacente antes de devolver a resposta. C["Cliente
GET /v1/users/42/posts"] --> B["URL base da API
casamento de rota: path + método"] B --> A["Auth · validação
rate limits"] A --> H["Handler
(o código da rota)"] H --> R[("Recurso:
posts do usuário 42")] R --> H --> C ``` ## Parâmetros de path vs. parâmetros de query A regra que encerra a maioria dos debates de design — **identidade no path, modificação na query**: | Pergunta que o parâmetro responde | Pertence a | Exemplo | | --- | --- | --- | | *Qual* recurso? | Path | `/users/42`, `/orders/2026-1187` | | Qual coleção *relacionada*? | Path | `/users/42/posts` | | Filtrar os resultados? | Query | `?status=published` | | Ordenar ou paginar? | Query | `?sort=-createdAt&limit=20` | | Ajustes opcionais de comportamento? | Query | `?include=author&fields=title` | A distinção tem consequências: parâmetros de path fazem parte da identidade do recurso (e da chave de cache); parâmetros de query moldam a representação. Um recurso alcançável apenas via query (`/getData?type=user&id=42`) é o clássico cheiro de nível 0 do qual a escada de maturidade [REST](/glossary/pt/api-rest/) parte. ## Como nomear bem seus endpoints Consumidores avaliam uma API pela lista de endpoints antes de ler uma linha de documentação: | Convenção | Bom | Ruim | | --- | --- | --- | | Substantivos, não verbos — o verbo é o método | `POST /orders` | `POST /createOrder` | | Coleções no plural | `/users`, `/users/42` | `/user/42` | | Minúsculas, com hífens | `/purchase-orders` | `/PurchaseOrders`, `/purchase_orders` | | Aninhamento raso (um nível) | `/users/42/posts` | `/users/42/posts/8/comments/3/likes` | | Prefixo de versão com política | `/v1/…` + janelas de deprecação | Quebrar a `/v1` em silêncio | | Padrões previsíveis | O mesmo formato para todo recurso | Cada recurso com o próprio dialeto | ## Protegendo endpoints: o checklist Todo endpoint é uma porta, e atacantes tentam todas — inclusive as que você esqueceu. O checklist compacto: **somente HTTPS**; **autenticação em todo endpoint** (nenhuma exceção "interna" alcançável pela internet); **autorização por recurso**, não só por API — o usuário 42 lendo `/users/43/orders` é o clássico buraco de broken object level authorization; **validação de entrada** em path, query e body; **[rate limits](/glossary/api-rate-limiting-throttling/)** dimensionados pelo custo do endpoint; **paginação com limites**, para que nenhum endpoint retorne coleções sem teto; **higiene de erros** (sem stack traces, sem vazar existência). E o item que os times mais esquecem: **inventário**. Endpoints "zumbis" — não documentados, deprecados-mas-vivos — têm entrada própria no [OWASP API Security Top 10](https://owasp.org/API-Security/): um endpoint que você não lembra é um endpoint que você não defende. ## Casos de uso comuns Onde pensar em endpoints paga o próprio salário: - **Consumir uma API de terceiros** — o catálogo de endpoints da documentação *é* o produto; dominar a anatomia é o jeito de lê-lo. - **Projetar uma API pública** — decisões de nomenclatura, posição de parâmetros e versionamento com as quais os consumidores convivem por anos. - **Depurar integrações** — reproduzir uma chamada do SDK como requisição crua ao endpoint com curl separa falha de cliente de falha de servidor. - **Configurar gateway e monitoramento** — [rate limits](/glossary/api-gateway-architecture/), alertas e regras de acesso são declarados por endpoint. - **Auditorias de segurança** — o inventário de endpoints é o mapa da superfície de ataque; a auditoria começa enumerando-o. ## Deveria ser um novo endpoint? Matriz de decisão | Situação | Resposta | | --- | --- | | Novo tipo de recurso | Novo endpoint (`/invoices`) | | Mesmo recurso, resultados mais estreitos | Endpoint existente + parâmetros de query | | Mesma URL, ação diferente | Mesmo path, método diferente | | Uma tela precisa de cinco endpoints | Considere um endpoint composto — mas veja o sprawl, abaixo | | Representação variante (campos, formato) | Parâmetro de query ou negociação de conteúdo, não um path novo | | Mudança que quebra formato ou semântica | Novo prefixo de versão, com janela de deprecação | ## Limitações e trade-offs - **Endpoint sprawl é dívida real.** Endpoints por tela e por time se acumulam; cada um é documentação, teste, monitoramento e superfície de ataque para sempre. Poucos endpoints bem projetados vencem muitos endpoints sob medida. - **Formatos fixos servem mal a alguns consumidores.** Um endpoint retorna o que retorna — o trade-off de [overfetching/underfetching](/glossary/overfetching-underfetching/) que APIs em formato de query existem para responder. - **URLs são contratos.** Renomear um endpoint quebra todos os consumidores; projete nomes com os quais você consiga conviver, porque migração significa versionamento, redirects e calendários de deprecação. - **O método é invisível na fala casual.** "O endpoint /users" esconde se você quer dizer leitura ou escrita — precisão importa em documentação, logs e regras de segurança. - **Contar endpoints não mede nada.** Uma API com 12 endpoints coerentes rotineiramente vence uma com 400 improvisados; o sinal de qualidade é governança, não volume. ## Endpoints de API no Back4app O Back4app é uma plataforma open-source de Backend as a Service (BaaS) que combina banco de dados gerenciado, APIs REST e GraphQL geradas automaticamente, autenticação, armazenamento de arquivos e funções serverless com Cloud Code. Aqui os endpoints são *derivados, não projetados*: criar uma classe `Todo` expõe na hora `/classes/Todo` e `/classes/Todo/:objectId` com o conjunto completo de métodos — o padrão de [APIs geradas automaticamente](/glossary/pt/apis-geradas-automaticamente/) — mais endpoints fixos para usuários, sessões, arquivos e funções, todos compartilhando uma única URL base, autenticação por chave e permissões por classe. As abas de código mostram a consequência prática: o SDK compõe endpoint, método e credenciais por você, e o checklist acima — consistência de nomes, auth em tudo, queries com limites, zero zumbis — chega como comportamento da plataforma, e não como disciplina de code review. Operações custom ganham endpoints do mesmo jeito: faça deploy de uma função de Cloud Code e `/functions/suaFuncao` passa a existir.