Batch requests

Why they matter

– Reduce overall delay: By grouping many calls together, you avoid repeating the setup for each one. This cuts down on the total time your requests take.
– Use less network resources: One batch request uses less internet data and fewer connections, which is especially helpful when using mobile data or on slow networks.
– Simplify error handling: Instead of dealing with results from many separate calls, you handle all responses together, making it easier to see which parts worked and which didn’t.

How batch requests work

Batch requests combine multiple API calls into one. Here’s how it generally works:

Structure and format

Batch requests are sent as a single HTTP request using a special format called multipart/mixed. This is how many Google APIs (like Gmail, Directory, or People API) handle multiple calls at once.

Inside this main request, each individual “part” has its own set of headers and acts like a tiny HTTP request. Each part includes its own method (like GET, POST), path, specific headers, and body. For example, each part typically starts with Content-Type: application/http and can have optional Content-ID headers.

Request composition

– All the individual calls within a batch request must be for the same API (e.g., all for Gmail API, or all for People API).
– Each inner call should only include the path part of the endpoint (e.g., /users/123), not the full web address.
– Headers set in the outer batch request apply to all the individual parts inside it, unless an individual part specifically provides its own header to override it. For example, if you send an authorisation header with the main batch request, it will be used for all the calls within it unless a specific call has its own authorisation header.

Response handling

– The server sends back a single response, also in multipart/mixed format.
– Each section of this response corresponds to one of your original inner requests. It will include its own HTTP status code (like 200 OK or 404 Not Found), specific headers, and the response body for that individual call.
– If you use Content-ID in your request parts, the server’s response parts will use a matching Content-ID (prefixed with “response-“) to help you link them back to your original requests.
– Important: The server does not guarantee the order in which the individual parts will be executed. If your process needs things to happen in a specific sequence (like reading data before updating it), you should send those requests separately, one after the other, instead of in a batch.

Why use batch requests

Using batch requests offers several advantages, especially when you need to make many API calls.

Improved performance

– Less delay: By combining many small calls into one, you avoid the repeated setup time for each individual request. This significantly reduces the overall time your requests take, which is especially important when you have many operations to perform.
– Smoother app: With fewer separate network connections, your application can run faster and more smoothly, even on slower or less reliable networks.

Reduced network overhead

By packaging multiple actions into a single request, you save on internet bandwidth and reduce the strain on both your application (client) and the server. This helps lower costs and keeps network usage low, which is ideal for mobile devices or connections with limited speed.

Simplified error handling

– You receive one combined response that tells you what happened with each individual request within the batch. This makes it easier to see which specific items succeeded or failed, and to decide if you need to try again or undo any changes.
– Some APIs even allow a batch to be transactional. This means if one request within the batch fails, the entire batch of operations is automatically undone, which helps keep your data consistent.

Better scalability

Batch requests help systems handle large amounts of operations more efficiently. By reducing the repeated work for each individual call, servers can process more tasks without getting overloaded.

Lower rate limit usage

Since a batch request counts as a single API call towards your limit, this method helps you stay within your API usage limits or quotas more easily. You send fewer main requests, making it simpler to manage your API consumption.

When to use batch requests

Batch requests are particularly useful in several situations where you need to make many API calls.

Large data upload or update scenarios

Batch requests are perfect when you need to send or change a large number of items at once. For example, syncing thousands of user profiles, files, or settings in a single go is much faster and more efficient than sending each update separately.

Mobile or client sync scenarios

If your app allows users to work offline (like on a phone or tablet), using a batch request to send all the changes they’ve made at once makes the synchronisation process smoother and more reliable when they reconnect.

Dashboard and workflow loading

When a user interface, like a dashboard, needs to pull data from several different places (e.g., charts, statistics, and user information), combining those requests into one batch can reduce delays and simplify how your application loads all that data.

High-volume processing (Bulk operations)

Batch requests excel when you need to process a huge number of records. Whether it’s tens of thousands or even millions, batching makes network usage more efficient and significantly cuts down the processing time for each record.

Rate limit sensitive environments

If the API you’re using has strict limits on how many calls you can make, packaging multiple individual requests into one batch call helps you stay within those usage limits more easily, while still performing many operations.

Atomic or transactional workflows

Some APIs allow “transactional batches” or “changesets.” This means that either all the operations within the batch succeed together, or if even one fails, the entire batch is rolled back. This is a good choice for workflows where you need to ensure all related records are created or changed consistently, or none at all.

Design considerations for batch requests

When designing or using batch requests, there are several important things to think about to ensure they work well.

Supported batch size limits

Strict limits
Many APIs have strict rules about how large a batch request can be. If you go over these limits, you’ll get errors like “Too many requests in a batch” or “Request payload size exceeds the limit.”

Check documentation
Microsoft Graph, for instance, allows a maximum of 20 smaller requests within one batch and requires you to use a specific /$batch endpoint. Always check the documentation for the specific API you are using to understand its limits.

Atomicity and dependencies

All or nothing (atomic)
Some batch designs allow for “atomic” behavior, meaning either all the operations within the batch succeed, or if even one fails, none of them succeed (the whole batch is rolled back). This prevents your data from becoming inconsistent due to partial changes.

Some may succeed (Bulk)
Other designs are “bulk” operations, where some items might succeed while others fail. For example, a bulk import might return success codes for some records and error codes for others, but it won’t undo the successful imports if one fails.

Order matters
If your tasks need to happen in a specific order (like creating a record then updating it), APIs might support a dependsOn or reference system. Microsoft Graph, for example, uses dependsOn fields in its JSON batching. If a task that another task depends on fails, the dependent calls will return a 424 Failed Dependency status.

Performance and server load

Balance is key
While batching reduces network overhead, you need to find a balance between the size of your batch and how much memory and processing power it uses. Very large batches can overload your client (app) or the server. Newer APIs might use “streaming formats” like application/json-seq to process records more efficiently and reduce memory strain.

Monitor load
If many clients send large batch requests at the same time, it can put a heavy load on your servers. Monitoring and analytics are crucial for choosing batch sizes that are safe and won’t cause problems.

REST principles and API style

Pragmatic compromise
Strictly, true REST design generally discourages combining many unrelated operations into a single request. Batch endpoints are often seen as a practical workaround. Some strict REST advocates might suggest using resource collection endpoints (e.g., DELETE /messages?id=1&id=2&id=3) instead of a full batch operation. However, batch endpoints can be very useful when performance and efficiency are more important than sticking strictly to REST purity.

Error and partial-failure handling

How to communicate results: You need to decide how your API will tell the client about the results of individual requests within a batch:
– Use HTTP 207 Multi-Status, which allows for per-item status codes.
– Return a single error code for the entire batch but include detailed information about individual successes/failures in the response body.
– Support transactional batches that automatically roll back if any part fails (atomic), or allow some parts to succeed while others fail (bulk).

Sync vs. Async processing

Asynchronous for long tasks: If the work in a batch might take a long time (e.g., processing thousands of items), consider an asynchronous design. In this case:
– The server immediately returns an HTTP 202 Accepted status with a Location header. This Location header points to another resource where the client can later check the status and results of the batch.
– The client then periodically checks (polls) that location until the batch is complete.

Synchronous for smaller batches: For smaller batches, returning an HTTP 207 Multi-Status immediately for synchronous processing (where the client waits for the full response) is simpler.

Start your data packed football platform now

Are you ready to take your football platform to the next level? Explore the Sportmonks Football API for reliable, real-time data that transforms user engagement. Ready to build your fantasy game? Check out our How-to guide and get started today.