API-clients en SDK’s configureren

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 voorbeeldadres 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;

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

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:

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

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.

Testen zonder de echte dienst: Test tegen een mock-API, niet tegen een voorbeeldadres

Verwante gidsen

Bronnen

• RFC 9457: Problem Details for HTTP APIs IETF
• Secrets Management Cheat Sheet OWASP
• Swagger Petstore sample API Swagger