Request Bundle

_{Published: 28 April 2025}

Known Uses

Dutch government APIs on developer.overheid.nl demonstrate varying levels of support for bulk requests, primarily through their implementation of the OData protocol. APIs from organizations such as CBS and the Tweede Kamer utilize OData v4, which inherently supports batch operations for both queries and data modifications. This pattern is rarely used within the energy sector: bulk data retrieval is handled outside the REST APIs via extract services or data-dump interfaces.

Some other known uses within Dutch government:

• Autorisaties API:
  curl -X GET https://autorisaties-api.vng.cloud/api/v1/applicaties?clientIds=123,456,789
  The ‘applications’ collection can be queried using multiple clientIds as query parameters.

• Using an older version of the BRP API, it was possible to query registered individuals using multiple citizen service numbers:
  curl -X GET https://www.haalcentraal.nl/haalcentraal/api/brp/ingeschrevenpersonen?burgerservicenummer=999993653,999991723,999995078

Discussion Input

Requesting multiple resources in a single API call raises several considerations:

• Response size limits
• Handling partial failures (e.g., what happens if one ID is invalid?)
• REST API design: should multiple values be passed as query parameters or as path parameters?

When designing APIs that need to retrieve multiple resources by their IDs, there are different approaches. Dutch government APIs use a single query parameter with comma-separated values: GET /customers?ids=a1,b2,c3. This approach is concise and widely used for filtering and OTTO’s API guidelines explicitly recommend this format for filtering by multiple values.: https://api.otto.de/portal/guidelines/r000062.

In the future, the QUERY HTTP method will likely be used for these bulk-request retrieval scenarios.

Recommended Reading

• https://apihandyman.io/api-design-tips-and-tricks-getting-creating-updating-or-deleting-multiple-resources-in-one-api-call/

This article provides practical guidance on handling multiple resources in a single API call.
Nice example: DELETE /resources?ids=ID1,ID2. The 207 Multi-Status response code is ideal when returning the outcome of multiple independent operations in one response. It allows each operation’s status to be reported individually within a single HTTP response.