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.

Basis-URL aus einem Beispiel

  1. Ihr Code API_BASE_URL=https://api.example-petstore.com
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. Beispieldomain: der Server eines anderen api.example-petstore.com
  4. 410 Gone Der Schlüssel landete bei einem Fremden: widerrufen Sie ihn

Basis-URL aus der Konfiguration

  1. Ihr Code API_BASE_URL=${API_BASE_URL}
  2. GET /v2/pet/42 Authorization: Bearer ••••
  3. Der echte Dienst
  4. 200 OK Anfrage und Schlüssel erreichen den richtigen Dienst
Zweimal derselbe Aufruf. Mit einer Adresse aus einem Beispiel landen Anfrage und Schlüssel auf einem Server, den Sie nicht kontrollieren, und diese Domain antwortet mit 410 Gone. Lesen Sie die Adresse deshalb aus der Konfiguration.

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;

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

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:

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

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.

Testen ohne den echten Dienst: Gegen eine Mock-API testen, nicht gegen einen Platzhalter

Quellen