Endpoints y respuestas estáticas

Una simulación sirve endpoints: cada uno es un método y una ruta que responden en la URL de la simulación. Vienen de dos orígenes. Los endpoints de OpenAPI salen de tu spec y responden con datos generados desde sus esquemas. Un endpoint estático lo defines tú: eliges un método y una ruta, escribes el cuerpo de la respuesta, y quien llame recibe ese cuerpo tal cual.

La vista Endpoints

Abre una simulación y arranca en Endpoints. Las dos clases aparecen ahí juntas, agrupadas por servicio.

• El interruptor enciende o apaga un endpoint. Un endpoint apagado queda fuera del próximo despliegue.
• El chip junto al interruptor es el tipo de contenido de un endpoint estático: JSON, TEXT, HTML o XML.
• Las reglas de latencia y de error también se ven en la fila, como los 300ms y el 10% 503 de arriba.
• Haz clic en una fila para abrir sus ajustes.

La búsqueda y el filtro por servicio están sobre la lista. Las listas largas se paginan de a 50 endpoints.

Dos clases de endpoints

Los endpoints de OpenAPI siguen un contrato. La spec define la forma de cada respuesta, así que el cuerpo es de solo lectura en la app, y cada llamada genera datos nuevos que encajan en el esquema. Para cambiarlos, cambia la spec.

Consulta Subir y actualizar una spec OpenAPI.

Un endpoint estático no tiene contrato. No hay archivo que subir ni esquema que cumplir: la respuesta es el texto del editor, y una llamada recibe estado 200 con exactamente ese texto. Eso lo vuelve la forma más rápida de poner una ruta en el aire:

• mockear una dependencia que no tiene spec OpenAPI,
• servir el payload exacto sobre el que se afirma un test,
• responder un health check, un blob de configuración o una página HTML chica,
• fijar una ruta de una spec a una respuesta fija mientras el resto se sigue generando.

Cómo se arma la URL

Una simulación responde en <dominio>/app/<tu-org>/<slug>, y cada endpoint vive debajo de eso. Un endpoint estático se sirve en su ruta tal como la escribiste; el GET /health de arriba responde en:

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

Los endpoints de OpenAPI responden bajo la ruta de montaje de la spec: el GET /pets de Petstore, montado en petstore, responde en /petstore/pets.

Reglas para una ruta estática:

• Empieza con /, no lleva barra final, y entra en 256 caracteres.
• Un segmento escrito como {name} coincide con cualquier valor: /users/{id}/orders responde para todos los id.
• Un endpoint por método y ruta. La misma ruta con dos métodos son dos endpoints.

Los endpoints estáticos se agrupan en servicios por su primer segmento de ruta: /v1/greeting y /v1/ping forman por sí solos el servicio v1. No hay nada que configurar; el servicio aparece con su primer endpoint y tiene sus propios ajustes del servicio.

Agregar un endpoint estático

En Endpoints, haz clic en Agregar y elige Endpoint estático.

El endpoint se crea al instante como GET /new con un cuerpo JSON vacío, y se abre para editar:

• Método: GET, POST, PUT, PATCH o DELETE.
• Tipo de contenido: application/json, text/plain, text/html o application/xml.
• Ruta: dónde responde.
• El editor guarda el cuerpo de la respuesta.

Cada cambio se guarda mientras escribes; no hay botón de guardar.

Cambiar una respuesta

Abre el endpoint, edita el cuerpo, haz clic en Desplegar. Unos segundos después la misma URL sirve la respuesta nueva. Quien llama no nota nada: la URL, el método y el tipo de contenido siguen coincidiendo, solo cambió el payload. Cuando el siguiente caso de prueba necesite otra respuesta, la cambias acá y no en el código.

Sobrescribir un endpoint de OpenAPI

Un endpoint estático con el mismo método y la misma ruta que un endpoint de OpenAPI se queda con esa ruta. La lista marca el par: la fila estática recibe un chip sobrescribe, y la de OpenAPI queda en gris con uno sobrescrito.

Esto es para la spec de cien endpoints donde una respuesta tiene que ser tuya. Sin sobrescrituras harías un fork de la spec y mantendrías la copia entera por ese único cambio. Acá la spec queda como la subiste: agrega un endpoint estático en la misma ruta completa, pega el payload, despliega. Los otros noventa y nueve siguen generando desde sus esquemas, y reemplazar el archivo de la spec más adelante deja la sobrescritura en su lugar.

El endpoint de OpenAPI sobrescrito no desapareció. Elimina el endpoint estático, o mueve su ruta, y vuelve a responder.

Latencia y errores

Un endpoint estático puede demorar y fallar a propósito. Ábrelo y pasa a la pestaña Comportamiento.

• Esperar antes de responder retiene la respuesta el tiempo indicado.
• Inyección de errores devuelve un estado de error para una parte de las solicitudes: la regla 10% -> 503 falla una llamada de cada diez. Cada solicitud tira un número del 1 al 100 y gana la regla con el porcentaje coincidente más bajo, así que las reglas no se suman; el porcentaje más alto es la tasa de error total.

Las llamadas restantes devuelven estado 200 con el cuerpo.

Un endpoint estático es un archivo

Por dentro, cada endpoint estático es un archivo, y no hay formato que aprender: la estructura de carpetas es la URL.

• Cada segmento de la ruta es una carpeta: /hello-world/v1 son las carpetas hello-world/v1/.
• El método es una carpeta más, en minúsculas: get/, post/.
• El cuerpo es el archivo index de adentro, y la extensión elige el tipo de contenido: .json, .txt, .html o .xml.

Así que POST /hello-world/v1 es el archivo hello-world/v1/post/index.json. Lees una URL y sabes el archivo; lees el árbol y sabes la API.

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

Deja fuera la carpeta del método y el archivo responde a GET. Una carpeta llamada {petId} coincide con cualquier valor, igual que en la app.

El editor de la app escribe esta estructura por ti al desplegar. También la puedes escribir tú y llevar los endpoints estáticos en control de versiones junto a tu código: una simulación portable corre esa misma estructura de carpetas directo desde tu disco, y la GitHub Action la despliega desde un repo. La plantilla portable trae justo este servicio hello-world para empezar.

Más que un cuerpo fijo

Ser estático solo describe la respuesta. En el aire estos endpoints se comportan como cualquier otro:

• La pestaña Upstream puede apuntar uno a un backend real, heredado de su servicio o sobrescrito para ese endpoint solo.
• Cada llamada queda grabada en el Historial.
• El explorador de API desplegado lo lista junto a los endpoints de OpenAPI.