example-petstore.com

Domaine d’exemple · Pas un service réel · Les visites depuis un navigateur affichent cette page · Les requêtes API reçoivent 410 Gone

Guide · API

Configurer les clients API et les SDK

Les requêtes vers des adresses comme api.example-petstore.com proviennent d’un code qui utilise encore une adresse d’exemple comme URL de base. Ce guide indique où se trouve généralement cette adresse, comment la déplacer dans la configuration et comment éviter que cela se reproduise.

URL de base copiée d’un exemple

  1. Votre code API_BASE_URL=https://api.example-petstore.com
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. Domaine d’exemple : le serveur de quelqu’un d’autre api.example-petstore.com
  4. 410 Gone La clé est arrivée chez un inconnu : révoquez-la

URL de base issue de la configuration

  1. Votre code API_BASE_URL=${API_BASE_URL}
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. Le vrai service
  4. 200 OK La requête et la clé arrivent au bon service
Deux fois le même appel. Avec une adresse copiée d’un exemple, la requête et sa clé aboutissent sur un serveur que vous ne contrôlez pas, et ce domaine répond 410 Gone. Lisez donc l’adresse depuis la configuration.

La réponse reçue

Toute requête avec un corps, vers un chemin de type API comme /v2/pet, ou qui demande du JSON, reçoit 410 Gone avec une description du problème (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. …"}

Ce domaine n’est pas l’API d’exemple Swagger Petstore, qui se trouve sur petstore.swagger.io.

Où se trouve l’adresse

  • une constante ou une valeur par défaut dans le code (BASE_URL = "https://api.example-petstore.com") ;
  • un fichier de configuration, un fichier .env ou une variable d’environnement copiés à partir d’un exemple ;
  • le champ host ou servers d’une description OpenAPI utilisée pour générer un client ;
  • une variable d’environnement Postman ou Insomnia comme {{baseUrl}} ;
  • des tests, des fixtures et des tâches CI exécutés sur une adresse fictive.

La configurer correctement

Lisez l’adresse depuis la configuration et générez une erreur explicite lorsqu’elle est absente :

# 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'));

Dans Postman ou Insomnia, définissez baseUrl pour chaque environnement et sélectionnez le bon environnement avant l’envoi.

Éviter le problème

Ajoutez au démarrage ou dans les tests une vérification qui rejette les adresses d’exemple :

# 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");
}

Dans votre propre documentation et vos propres exemples, utilisez des noms réservés à cet usage, comme api.example.com. Consultez la page domaines d’exemple.

Clés envoyées

Si des requêtes contenaient une clé API, un jeton, un mot de passe ou un cookie de session, ceux-ci ont atteint le mauvais serveur. Révoquez-les auprès du service qui les a émis et générez-en de nouveaux. Identifiants divulgués : que faire maintenant.

Tester sans le vrai service : Tester avec une API simulée (mock), pas une adresse d’exemple

Sources