v1

Verzoeken doen

Basis-URL, authenticatieheader, paginering en foutafhandeling.

De Verbleif-API is een API Platform JSON-LD-API. Elk verzoek wordt geauthenticeerd met het bearer token dat je verkreeg bij Authenticatie.

Basis-URL en headers

Stuur het access token mee in de Authorization-header. Vraag om JSON-LD met Accept, en stuur bij schrijfacties JSON-LD-bodies met Content-Type:

curl https://api.verbleif.com/api/reservations \
  -H "Authorization: Bearer JOUW_ACCESS_TOKEN" \
  -H "Accept: application/ld+json"
Header Wanneer Waarde
Authorization Elk verzoek Bearer JOUW_ACCESS_TOKEN
Accept Elk verzoek application/ld+json
Content-Type Request-bodies (POST, PUT, …) application/ld+json
Content-Type Gedeeltelijke updates (PATCH) application/merge-patch+json

De API onderhandelt alleen JSON-LD (application/ld+json) voor resource-antwoorden en fouten. Gewone application/json is geen ondersteund responseformaat. OpenAPI- / HTML-documentatie gebruikt aparte mediatypen (application/vnd.openapi+json, text/html) en is niet bedoeld voor normale API-aanroepen.

Paginering

Collectie-endpoints zijn gepagineerd met API Platform Hydra- / JSON-LD-collecties.

Queryparameter Standaard Opmerkingen
page 1 Paginanummer
perPage 100 Paginagrootte; clients mogen dit verhogen tot maximaal 250
partial niet gezet (false) Bij true slaat de API de totale telling over

Een typische eerste pagina ziet er zo uit:

{
  "member": [ /* …resources… */ ],
  "totalItems": 160,
  "view": {
    "@type": "PartialCollectionView",
    "first": "/api/clients?page=1",
    "last": "/api/clients?page=2",
    "next": "/api/clients?page=2"
  }
}

Totale telling (totalItems)

totalItems staat alleen op de eerste pagina (page=1, of weggelaten). Latere pagina’s laten het weg, zodat de API geen volledige count-query hoeft te doen. Hetzelfde geldt bij partial=true: ook pagina 1 heeft dan geen totalItems.

Heb je het totaal nodig, lees het uit het eerste antwoord en blader verder via de links in view.

Volg de next-link in view tot die ontbreekt. Hardcode geen paginanummers en ga niet uit van een andere vaste paginagrootte dan de standaarden hierboven.

Rate limits

Geauthenticeerde App Store- / API Platform-aanroepen naar normale resource-endpoints (/api/… met een bearer token) hebben op dit moment geen globale rate limit per app of per token in de API.

Endpoints die gevoelig zijn voor misbruik gebruiken Symfony’s token bucket-rate limiter (token_bucket): een burst-capaciteit die met een vast tempo bijgevuld wordt. Is de bucket leeg, dan antwoordt de API met 429 Too Many Requests en een Retry-After-header (seconden tot je opnieuw mag proberen). Handel 429 altijd af en respecteer Retry-After.

Voorbeelden van endpoint-specifieke buckets (geen algemene API-quota):

Gebied Bucket Burst (limit) Bijvullen
Publieke gastmeldingen (schrijven / settings / discovery) per client-IP en per locatie-hash 50 10 tokens / minuut
Publieke gastmeldingen (lezen) per client-IP en per locatie-hash 30 6 tokens / minuut
Wachtwoordherstel (op IP) per IP 100 20 tokens / minuut
Wachtwoordherstel (op gebruikersnaam) per gebruikersnaam 5 1 token / minuut

Login-discovery op de auth-service gebruikt hetzelfde token-bucket-algoritme (aparte buckets per IP en per gebruikersnaam). Die limieten gelden voor discovery, niet voor gewoon App Store-API-verkeer.

Er is geen gepubliceerd globaal “verzoeken per minuut per app”-cijfer voor geauthenticeerde collectie- en item-endpoints. Krijg je daar toch 429, behandel het als een uitzonderlijke throttle (edge of endpoint-specifiek) en wacht volgens Retry-After.

Fouten

De API gebruikt standaard HTTP-statuscodes. Foutantwoorden komen ook als JSON-LD (zelfde Accept) en bevatten machinaal leesbare velden zoals status en detail:

{
  "status": 403,
  "detail": "This app is not authorized for the requested scope."
}
  • 401 - het access token ontbreekt of is verlopen. Vernieuw het en probeer opnieuw.
  • 403 - het token is geldig, maar de app mist de vereiste scope.
  • 404 - de resource bestaat niet of valt buiten de verleende locaties.
  • 429 - je wordt gelimiteerd; respecteer Retry-After.
  • 406 - de Accept-header komt niet overeen met een ondersteund formaat (gebruik application/ld+json).

Voor App Store-integraties die wijzigingen vanuit een extern systeem naar Verbleif pushen, zie Webhooks.