Veelgebruikte recepten voor API-automatisering

De API geeft HTTP 429 terug met een Retry-After-header zodra je over de 200 requests per minuut per IP gaat. Een script dat volgens een schema polt, zoals hieronder, moet controleren op een 429 en de tijd uit die header aanhouden in plaats van meteen opnieuw te proberen.

1. Controleer serverstatus volgens een schema

Een cronjob die een endpoint uitleest en op het resultaat reageert, is de eenvoudigste vorm van automatisering, en vaak het eerste wat teams opzetten. Dit voorbeeld controleert elke vijf minuten de status van een server en schrijft een regel naar een logbestand als die niet draait.

# crontab -e
*/5 * * * * /usr/local/bin/check-server-status.sh >> /var/log/server-status.log 2>&1

#!/usr/bin/env bash
# check-server-status.sh
# Illustratief patroon, haal het exacte endpoint-pad uit de API-naslag in Portal.
set -euo pipefail

API_KEY="<your-api-key>"
SERVER_ID="<server-id>"
STATUS_URL="https://api.worldstream.com/<family>/v1/<command>/$SERVER_ID"

status=$(curl -s -H "X-API-Key: $API_KEY" \
  "$STATUS_URL" \
  | jq -r '.status')

echo "$(date -u +%FT%TZ) server=$SERVER_ID status=$status"

if [ "$status" != "running" ]; then
  echo "WARNING: $SERVER_ID is not running (status: $status)"
fi

Houd de API-key buiten het script zelf. Lees hem uit een environment variable of een secrets manager, en geef de key alleen de rechten die nodig zijn, read-only toegang tot de status in plaats van een key met volledige toegang, als je key-permissies dat detailniveau ondersteunen.

2. Roteer een API-key voordat die verloopt

Keys maak je aan onder Developers → API → Keys in Portal, met een Key Name, een Expires In-waarde (30 dagen, 90 dagen, 180 dagen of 1 jaar) en een Permissions-niveau (Full access, Read only of Custom). Zodra die vervaldatum is verstreken, stopt de key met werken. Wacht niet tot een script in productie faalt: genereer de vervangende key van tevoren en wissel hem om in je secrets store.

Staat de IP-allowlist voor de API bij jouw account op Enforce? Zorg dan dat de host die de nieuwe key aanmaakt eerst op de allowlist staat, anders wordt het verzoek om die aan te maken geweigerd. Bekijk Recent API key denials op het tabblad Keys als een rotatiescript begint te falen met een 403.

#!/usr/bin/env bash
# rotate-api-key.sh
# Illustratief patroon, controleer het actuele endpoint in de API-naslag in Portal.
set -euo pipefail

OLD_KEY="<current-api-key>"

new_key_response=$(curl -s -X POST \
  -H "X-API-Key: $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '<request body, zie de API-naslag in Portal>' \
  "https://api.worldstream.com/<family>/v1/<command>")

new_key=$(echo "$new_key_response" | jq -r '.secret')

# Store the new key in your secrets manager here, then update
# whatever reads it (CI variables, a systemd EnvironmentFile, etc.)
echo "New key created, store it now: $new_key"

# Only revoke the old key once every consumer has been switched over.

Behandel key-rotatie als een proces in twee stappen: maak eerst de nieuwe key aan en rol die uit, controleer dat alles wat ervan afhankelijk is nog werkt, en trek dan pas de oude key in. Trek je de oude key in voordat de nieuwe overal actief is, dan breekt alles wat nog de oude key gebruikt.

3. Stuur een Slack-melding als een event afgaat

Dit recept gebruikt de API niet rechtstreeks, maar Webhooks, een aparte functie onder Developers → Webhooks in Portal. Voeg daar een webhook toe met een Slack-compatibele bestemmings-URL, zet het formaat op Slack, en abonneer de webhook op het juiste topic via het optionele, kommagescheiden Topics-veld (laat het leeg om alle event-types te ontvangen). Haal de namen van de topics van de Webhooks-pagina in Portal. Worldstream post naar de URL zodra het event plaatsvindt, je hoeft er niet op te pollen.

Schakel alleen de topics in waar je ook echt actie op onderneemt. Een webhook die op elk event-type afgaat, wordt al snel gedempt of genegeerd, en dat ondermijnt het hele doel ervan.

4. Webhook-events doorsturen naar je eigen monitoring- of ticketingsysteem

Werkt jouw team niet in Slack? Zet dan het formaat van de webhook op Generic JSON en wijs een endpoint aan dat je zelf beheert, bijvoorbeeld een kleine receiver die events doorstuurt naar je monitoring-stack, ticketingsysteem of interne chattool.

# Illustrative receiver, adapt the framework and payload
# handling to whatever your monitoring/ticketing system expects.
# The event_type value below ("resource.event") is a placeholder.
# Use the real topic and event names shown on the Webhooks page in Portal.
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/worldstream", methods=["POST"])
def worldstream_webhook():
    payload = request.get_json()
    event_type = payload.get("event")

    if event_type == "resource.event":
        # forward into your own system here
        pass

    return "", 204

Controleer inkomende requests aan de hand van het signing secret voordat je erop reageert, zodat een request dat alleen je endpoint-URL kent niets op eigen houtje kan triggeren. De exacte verificatiemethode (welke header de signature bevat en hoe die wordt berekend) haal je uit de Webhooks-documentatie in Portal.