Je eerste API-call · vlows wiki

Log eerst in op de console en maak een API-key met API-gebruik lezen. Bewaar de key in de geheime configuratie van je koppeling. Daarna kun je de onderstaande aanvraag uitvoeren.

Kies de juiste basis-URL

Alle API-aanvragen gaan naar https://api.vlows.io. Het pad bepaalt welke gegevens je opvraagt of aanlevert. De console gebruik je om in te loggen en keys te beheren; je koppeling gebruikt de API-key bij elke aanvraag.

Authenticatie meesturen

Elke aanvraag met een API-key gebruikt de header Authorization: Bearer <key>. Verstuur keys niet als queryparameter. De voorbeelden nemen aan dat je API_KEY via je eigen secretconfiguratie hebt ingesteld.

API_URL=https://api.vlows.io
curl --fail-with-body --silent --show-error \
  "$API_URL/account/v1/usage" \
  -H "Authorization: Bearer $API_KEY"

Dit endpoint vereist usage:read. Een key die alleen leveringen mag lezen krijgt hier 403.

Een antwoord lezen

Succes gebruikt een envelope met data en een lege error. Een nieuwe organisatie kan nog geen geregistreerd gebruik hebben:

{"data": [], "error": null}

Bij fouten is data leeg en bevat error een code en uitleg. De request_id is bruikbaar bij onderzoek. Deel daarbij nooit je volledige sleutel.

{
  "data": null,
  "error": {
    "code": "forbidden_scope",
    "message": "Required permission is missing",
    "request_id": "<request-uuid>"
  }
}

Voorbeeld in Python

Dit voorbeeld gebruikt alleen de standaardbibliotheek en een key met usage:read.

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

base = os.environ.get("API_URL", "https://api.vlows.io")
request = Request(
    base + "/account/v1/usage/requests",
    headers={"Authorization": "Bearer " + os.environ["API_KEY"]},
)
try:
    with urlopen(request, timeout=15) as response:
        rows = json.load(response)["data"]
        for row in rows:
            print(row["route"], row["status"], row["units"])
except HTTPError as error:
    details = json.load(error)["error"]
    print(error.code, details["code"], details.get("request_id"))

Controleer je aanvraag in de console

Open API-gebruik in de console. Zoek je aanvraag op tijdstip, keynaam en endpoint. Een gebruiksaanvraag wordt na het ophalen van de gegevens geregistreerd: bij je eerste aanvraag kan data dus leeg zijn. Herlaad de gebruikspagina of wacht op de automatische verversing na 60 seconden.

Wil je stoppen met deze koppeling, trek dan de key in onder API-keys. Nieuwe aanvragen krijgen daarna 401; eerdere gebruiksgegevens blijven zichtbaar.

Betrouwbaar integreren

Gebruik JSON voor requestbodies, met Content-Type: application/json. De API wijst onbekende invoervelden af. Houd de body onder de huidige limiet van 2 MiB. Stel een timeout in en behandel fouten bewust.

Nieuwe leveringen, gebeurtenissen en pogingen vereisen een Idempotency-Key. Updates aan een levering vereisen een If-Match-versie. Deze mechanismen voorkomen dubbele verwerking en onbedoeld overschrijven. Zie Fouten & opnieuw proberen.

Verder bouwen

Gebruik het endpointoverzicht om de juiste route en scope te kiezen. De OpenAPI-specificatie kun je downloaden; de responseschema's zijn in deze pilot nog algemeen. Raadpleeg daarom ook de uitgewerkte voorbeelden en pakketvelden.