example-petstore.com

Voorbeelddomein · Geen echte dienst · Bezoekers met een browser zien deze pagina · API-verzoeken krijgen 410 Gone

Gids · API’s

API-clients en SDK’s configureren

Verzoeken naar adressen zoals api.example-petstore.com komen uit code die nog een voorbeeldadres als basis-URL gebruikt. Deze gids laat zien waar dat adres meestal staat, hoe je het naar de configuratie verplaatst en hoe je voorkomt dat het opnieuw gebeurt.

Het antwoord dat je krijgt

Elk verzoek met een body, naar een pad zoals dat van een API (bijvoorbeeld /v2/pet), of dat om JSON vraagt, krijgt 410 Gone met een probleembeschrijving (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. …"}

Dit domein is niet de voorbeeld-API Swagger Petstore; die staat op petstore.swagger.io.

Waar het adres staat

  • een constante of standaardwaarde in de code (BASE_URL = "https://api.example-petstore.com");
  • een configuratiebestand, .env-bestand of omgevingsvariabele die uit een voorbeeld is overgenomen;
  • het veld host of servers van een OpenAPI-beschrijving waarmee een client is gegenereerd;
  • een omgevingsvariabele in Postman of Insomnia, zoals {{baseUrl}};
  • tests, fixtures en CI-jobs die tegen een plaatshouder draaien.

Het goed configureren

Lees het adres uit de configuratie en laat het programma duidelijk falen als het ontbreekt:

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

Stel in Postman of Insomnia baseUrl per omgeving in, en kies de juiste omgeving voor je een verzoek verstuurt.

Voorkomen

Voeg bij het opstarten of in de tests een controle toe die voorbeeldadressen weigert:

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

Gebruik in je eigen documentatie en voorbeelden namen die daarvoor zijn gereserveerd, zoals api.example.com. Zie voorbeelddomeinen.

Verstuurde sleutels

Stuurden de verzoeken een API-sleutel, token, wachtwoord of sessiecookie mee, dan zijn die op de verkeerde server terechtgekomen. Trek ze in bij de dienst die ze heeft uitgegeven en vraag nieuwe aan. Gelekte sleutels: wat je nu doet.

Bronnen