example-petstore.com

Beispieldomain · Kein aktiver Dienst · Browseraufrufe zeigen diese Seite · API-Anfragen erhalten 410 Gone

Anleitung · APIs

API-Clients und SDKs konfigurieren

Anfragen an Adressen wie api.example-petstore.com stammen von Code, der noch eine Beispieladresse als Basis-URL verwendet. Diese Anleitung zeigt, wo diese Adresse üblicherweise steht, wie Sie sie in die Konfiguration verlagern und wie Sie verhindern, dass das erneut passiert.

Die Antwort, die Sie erhalten

Jede Anfrage mit einem Body, an einen API-typischen Pfad wie /v2/pet oder mit der Anforderung von JSON erhält 410 Gone mit einer Problembeschreibung (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. …"}

Diese Domain ist nicht die Beispiel-API Swagger Petstore; diese finden Sie unter petstore.swagger.io.

Wo die Adresse steht

  • eine Konstante oder ein Standardwert im Code (BASE_URL = "https://api.example-petstore.com");
  • eine Konfigurationsdatei, .env-Datei oder Umgebungsvariable, die aus einem Beispiel kopiert wurde;
  • das Feld host oder servers einer OpenAPI-Beschreibung, aus der ein Client generiert wird;
  • eine Umgebungsvariable in Postman oder Insomnia wie {{baseUrl}};
  • Tests, Fixtures und CI-Jobs, die gegen einen Platzhalter laufen.

Richtig konfigurieren

Lesen Sie die Adresse aus der Konfiguration und brechen Sie mit einer deutlichen Fehlermeldung ab, wenn sie fehlt:

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

Legen Sie in Postman oder Insomnia baseUrl je Umgebung fest und wählen Sie vor dem Senden die richtige Umgebung aus.

Vorbeugen

Fügen Sie beim Start oder in den Tests eine Prüfung hinzu, die Beispieladressen ablehnt:

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

Verwenden Sie in Ihrer eigenen Dokumentation und Ihren Beispielen Namen, die dafür reserviert sind, etwa api.example.com. Siehe Beispieldomains.

Gesendete Schlüssel

Enthielten Anfragen einen API-Schlüssel, ein Token, ein Passwort oder ein Sitzungscookie, haben diese den falschen Server erreicht. Widerrufen Sie sie bei dem Dienst, der sie ausgestellt hat, und stellen Sie neue aus. Offengelegte Zugangsdaten: was jetzt zu tun ist.

Quellen