Als developer van een TSA wil ik efficiënt bulk calls kunnen uitvoeren

[sergei-maertens]

...zodat ik HTTP/connection overhead kan omzeilen.

Inspiratie

Dit is een feature request op alle API's geïnspireerd op de Facebook Graph API die batch requests ondersteunt. Ik heb persoonlijk goeie ervaringen met deze opzet als consumer.

Wat is het?

Als client moet ik vaak een aantal API calls tegelijk/in parallel doen. Bijvoorbeeld:

• ophalen lijst van zaaktypen
• elk zaaktype heeft een lijst van statustypen
• ik kan alle statustypen tegelijk / in parallel ophalen eenmaal ik de zaaktypen heb opgehaald

Dit kan in de meeste programmeertalen parallel door gebruikt te maken van één of andere vorm van threading of async/await programmeren. Echter, dit betekent dat je voor elke HTTP call nog steeds de verbinding met de API opstelt en de request maakt, met alle overhead van doen. Dit zorgt ook voor een piek-belasting bij de API - als je 50 parallelle requests afvoert, dan moet deze API ook 50 connecties tegelijk aankunnen.

Een API endpoint voor batch requests biedt hier een oplossing - je stuurt 1 HTTP request met daarin uitgedrukt welke calls je wil uitvoeren, en de API zelf voert deze dan in parallel uit. De antwoorden krijg je in dezelfde volgorde terug als de requests:

Voorbeeld:

POST /api/v1/batch HTTP/1.1
Host: localhost:8000
Accept-Crs: EPSG:4326
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImNsaWVudF9pZGVudGlmaWVyIjoic2VyZ2VpIn0.eyJpc3MiOiJzZXJnZWkiLCJpYXQiOjE2MDIwODczMTAsImNsaWVudF9pZCI6InNlcmdlaSIsInVzZXJfaWQiOiIiLCJ1c2VyX3JlcHJlc2VudGF0aW9uIjoiIn0.2TKqXFFfkvrWArYd_qFjicz_bT17OeDnHCu0WEjgBeo
Content-Type: application/json

[
    {"method": "get", "url": "/zaken/api/v1/zaken?zaaktype=http://localhost:8000/catalogi/api/v1/zaaktypen/4b43a910-db79-4daa-a492-a5312d12d894"},
    {"method": "get", "url": "/documenten/api/v1/"},
    {"method": "get", "url": "/besluiten/api/v1/besluiten"}
]

Voordelen

• minimale HTTP overhead
• overige connecties blijven beschikbaar voor andere clients
• sneller dan client-side paralleliseren (factor 3 in mijn tests met drie requests!)
• generiek toepasbaar, niet gebonden aan semantiek van API's
• lost een aantal van de filter-userstories op met een andere insteek

Risico's/vragen

• duidelijke afstemming van minimaal aantal gelijktijdige requests nodig, zodat clients van dit minimum uit kunnen gaan
• wat met endpoint-specifieke headers?

Proof-of-concept

Ik heb een werkende proof of concept hiervan gemaakt in Open Zaak: https://github.com/open-zaak/open-zaak/pull/737