Endpoints e respostas estáticas

Atualizado em 29 de set. de 2026·7 min de leitura

Uma simulação serve endpoints: cada um é um método e um caminho respondendo na URL da simulação. Eles vêm de duas origens. Os endpoints de OpenAPI vêm do seu spec e respondem com dados gerados a partir dos schemas dele. Um endpoint estático é você que define: escolhe um método e um caminho, digita o corpo da resposta, e quem chama recebe esse corpo sem mudança nenhuma.

A visão Endpoints

Abra uma simulação e ela começa em Endpoints. Os dois tipos aparecem lá juntos, agrupados por serviço.

A chave liga ou desliga um endpoint. Um endpoint desligado fica de fora do próximo deploy.
O chip ao lado da chave é o tipo de conteúdo de um endpoint estático: JSON, TEXT, HTML ou XML.
As regras de latência e de erro também aparecem na linha, como o 300ms e o 10% 503 acima.
Clique em uma linha para abrir as configurações dela.

A busca e o filtro por serviço ficam acima da lista. Listas longas paginam de 50 em 50 endpoints.

Dois tipos de endpoint

Os endpoints de OpenAPI seguem um contrato. O spec define o formato de cada resposta, então o corpo é de leitura no app, e cada chamada gera dados novos que cabem no schema. Para mudar eles, mude o spec.

Veja Subir e atualizar um spec OpenAPI.

Um endpoint estático não tem contrato. Não tem arquivo para subir nem schema para respeitar: a resposta é o texto do editor, e uma chamada recebe status 200 com exatamente aquele texto. É isso que faz dele o jeito mais rápido de colocar uma rota no ar:

mockar uma dependência que não tem spec OpenAPI,
servir o payload exato em que um teste faz asserção,
responder um health check, um blob de configuração ou uma página HTML pequena,
fixar uma rota de um spec em uma resposta fixa enquanto o resto continua gerado.

Como a URL é montada

Uma simulação responde em <domínio>/app/<sua-org>/<slug>, e todo endpoint fica abaixo disso. Um endpoint estático é servido no caminho do jeito que você digitou; o GET /health acima responde em:

https://api.mockz.io/app/docs-shots/tidy-valley/health

Os endpoints de OpenAPI respondem no caminho de montagem do spec: o GET /pets do Petstore, montado em petstore, responde em /petstore/pets.

Regras para um caminho estático:

Ele começa com /, não tem barra no fim, e cabe em 256 caracteres.
Um segmento escrito como {name} casa com qualquer valor: /users/{id}/orders responde para todo id.
Um endpoint por método e caminho. O mesmo caminho com dois métodos são dois endpoints.

Os endpoints estáticos se agrupam em serviços pelo primeiro segmento do caminho: /v1/greeting e /v1/ping formam sozinhos o serviço v1. Não tem nada para configurar; o serviço aparece com o primeiro endpoint dele e tem as próprias configurações do serviço.

Adicionar um endpoint estático

Em Endpoints, clique em Adicionar e escolha Endpoint estático.

O menu Adicionar da visão Endpoints com as entradas Endpoint estático e Spec OpenAPI — O menu Adicionar

O endpoint é criado na hora como GET /new com um corpo JSON vazio, e abre para edição:

Um endpoint estático aberto para edição: método, tipo de conteúdo, caminho e o editor do corpo da resposta — Um endpoint estático aberto para edição

Método: GET, POST, PUT, PATCH ou DELETE.
Tipo de conteúdo: application/json, text/plain, text/html ou application/xml.
Caminho: onde ele responde.
O editor guarda o corpo da resposta.

Toda mudança é salva enquanto você digita; não tem botão de salvar.

As edições valem no próximo deploy. A simulação no ar continua servindo o que foi publicado por último até você clicar em Fazer deploy.

Mudar uma resposta

Abra o endpoint, edite o corpo, clique em Fazer deploy. Alguns segundos depois a mesma URL serve a resposta nova. Quem chama não percebe nada: a URL, o método e o tipo de conteúdo continuam batendo, só o payload mudou. Quando o próximo caso de teste precisar de outra resposta, você muda aqui e não no código.

Sobrescrever um endpoint de OpenAPI

Um endpoint estático com o mesmo método e o mesmo caminho de um endpoint de OpenAPI assume aquela rota. A lista marca o par: a linha estática ganha um chip sobrescreve, e a de OpenAPI fica cinza com um sobrescrito.

A lista de Endpoints filtrada em pets: um endpoint estático marcado sobrescreve acima do endpoint de OpenAPI em cinza marcado sobrescrito — A consulta de pet do Petstore, sobrescrita por um endpoint estático no mesmo caminho

Isso é para o spec de cem endpoints em que uma resposta tem que ser sua. Sem sobrescrita você faria um fork do spec e manteria a cópia inteira por causa daquela mudança só. Aqui o spec fica como você subiu: adicione um endpoint estático no mesmo caminho completo, cole o payload, faça o deploy. Os outros noventa e nove continuam gerando a partir dos schemas deles, e trocar o arquivo do spec depois deixa a sobrescrita no lugar.

O endpoint de OpenAPI sobrescrito não sumiu. Apague o endpoint estático, ou mova o caminho dele, e ele volta a responder.

Latência e erros

Um endpoint estático pode demorar e falhar de propósito. Abra ele e vá para a aba Comportamento.

A aba Comportamento de um endpoint estático com 300 ms de espera e uma regra de erro 503 em 10 por cento — Latência e uma regra de erro em um endpoint estático

Esperar antes de responder segura a resposta pelo tempo indicado.
Injeção de erros devolve um status de erro para uma parte das requisições: a regra 10% -> 503 derruba uma chamada em cada dez. Cada requisição sorteia um número de 1 a 100 e ganha a regra com o menor percentual que bate, então as regras não se somam; o maior percentual é a taxa total de erro.

As chamadas restantes devolvem status 200 com o corpo.

Um endpoint estático é um arquivo

Por baixo, cada endpoint estático é um arquivo, e não tem formato para aprender: a estrutura de pastas é a URL.

Cada segmento do caminho é uma pasta: /hello-world/v1 são as pastas hello-world/v1/.
O método é mais uma pasta, em minúsculas: get/, post/.
O corpo é o arquivo index lá dentro, e a extensão escolhe o tipo de conteúdo: .json, .txt, .html ou .xml.

Então POST /hello-world/v1 é o arquivo hello-world/v1/post/index.json. Você lê uma URL e sabe o arquivo; lê a árvore e sabe a API.

services/
  hello-world/
    v1/
      get/
        index.json    # GET /hello-world/v1
      post/
        index.json    # POST /hello-world/v1

Deixe a pasta do método de fora e o arquivo responde a GET. Uma pasta chamada {petId} casa com qualquer valor, igual no app.

O editor do app escreve essa estrutura para você no deploy. Você também pode escrever ela e guardar os endpoints estáticos no controle de versão junto do seu código: uma simulação portable roda essa mesma estrutura de pastas direto do seu disco, e a GitHub Action publica ela a partir de um repo. O template portable traz exatamente este serviço hello-world para você começar.

Mais que um corpo fixo

Ser estático só descreve a resposta. No ar esses endpoints se comportam como qualquer outro:

A aba Upstream pode apontar um deles para um backend de verdade, herdado do serviço ou sobrescrito só para aquele endpoint.
Toda chamada nele é gravada no Histórico.
O explorador de API publicado lista ele ao lado dos endpoints de OpenAPI.