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.

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 un espace réservé.

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

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 :

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

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.

Sources