example-petstore.com

Dominio de ejemplo · No es un servicio activo · Las visitas desde el navegador muestran esta página · Las solicitudes a la API reciben 410 Gone

Guía · API

Configurar clientes de API y SDK

Las solicitudes a direcciones como api.example-petstore.com vienen de código que todavía usa una dirección de ejemplo como URL base. Esta guía muestra dónde suele estar esa dirección, cómo trasladarla a la configuración y cómo evitar que vuelva a ocurrir.

URL base copiada de un ejemplo

  1. Tu código API_BASE_URL=https://api.example-petstore.com
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. Dominio de ejemplo: el servidor de otra persona api.example-petstore.com
  4. 410 Gone La clave llegó a un desconocido: revócala

URL base desde la configuración

  1. Tu código API_BASE_URL=${API_BASE_URL}
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. El servicio real
  4. 200 OK La solicitud y la clave llegan al servicio correcto
La misma llamada dos veces. Con una dirección copiada de un ejemplo, la solicitud y su clave acaban en un servidor que no controlas, y este dominio responde con 410 Gone. Lee la dirección desde la configuración.

La respuesta que recibes

Toda solicitud con cuerpo, a una ruta de estilo API como /v2/pet o que pida JSON, recibe 410 Gone con una descripción del problema (RFC 9457):

HTTP/1.1 410 Gone
Content-Type: application/problem+json; charset=utf-8

{"type":"https://example-petstore.com/#where","title":"Example domain, not a real service",
 "status":410,"detail":"api.example-petstore.com is an example domain used in documentation. …"}

Este dominio no es la API de ejemplo Swagger Petstore, que está en petstore.swagger.io.

Dónde está la dirección

  • una constante o un valor predeterminado en el código (BASE_URL = "https://api.example-petstore.com");
  • un archivo de configuración, un archivo .env o una variable de entorno copiados de un ejemplo;
  • el campo host o servers de una descripción de OpenAPI usada para generar un cliente;
  • una variable de entorno de Postman o Insomnia, como {{baseUrl}};
  • pruebas, datos de prueba y tareas de CI que se ejecutan contra un marcador de posición.

Configurarla correctamente

Lee la dirección desde la configuración y haz que falle de forma visible cuando falte:

# Python: read the address from configuration, not from the code
import os
BASE_URL = os.environ["API_BASE_URL"]

// JavaScript / Node.js
const baseURL = process.env.API_BASE_URL;

// PHP 8
$baseUrl = getenv('API_BASE_URL') ?: throw new RuntimeException('API_BASE_URL is not set');
# Python, httpx
client = httpx.Client(base_url=os.environ["API_BASE_URL"])

// Node.js, axios
const api = axios.create({ baseURL: process.env.API_BASE_URL });

# Generated OpenAPI client (Python)
configuration = Configuration(host=os.environ["API_BASE_URL"])

// PHP, Guzzle
$client = new GuzzleHttp\Client(['base_uri' => getenv('API_BASE_URL')]);

// PHP, Symfony HttpClient
$client = Symfony\Component\HttpClient\HttpClient::createForBaseUri(getenv('API_BASE_URL'));

En Postman o Insomnia, define baseUrl por entorno y selecciona el entorno correcto antes de enviar.

Evitarlo

Añade una comprobación al inicio o en las pruebas que rechace las direcciones de ejemplo:

# Python
import os, re
base = os.environ["API_BASE_URL"]
if re.search(r"example-(petstore|commerce-host)\.com", base):
    raise RuntimeError(f"API_BASE_URL still points at an example domain: {base}")

// PHP
$base = getenv('API_BASE_URL') ?: '';
if (preg_match('/example-(petstore|commerce-host)\.com/', $base)) {
    throw new RuntimeException("API_BASE_URL still points at an example domain: $base");
}

En tu propia documentación y tus ejemplos, usa nombres reservados para ese fin, como api.example.com. Consulta dominios de ejemplo.

Claves que se enviaron

Si las solicitudes incluían una clave de API, un token, una contraseña o una cookie de sesión, llegaron al servidor equivocado. Revócalos en el servicio que los emitió y genera otros nuevos. Credenciales filtradas: qué hacer ahora.

Probar sin el servicio real: Prueba con una API simulada (mock), no con una dirección de ejemplo

Fuentes