Skip to main content
Version: 3.1

batch-requests

Description#

The batch-requests plugin accepts multiple requests, sends them from APISIX via HTTP pipelining, and returns an aggregated response to the client.

This improves the performance significantly in cases where the client needs to access multiple APIs.

note

The HTTP headers for the outer batch request (except for Content- headers like Content-Type) apply to every request in the batch.

If the same HTTP header is specified in both the outer request and on an individual call, the header of the individual call takes precedence.

Attributes#

None.

API#

This plugin adds /apisix/batch-requests as an endpoint.

note

You may need to use the public-api plugin to expose this endpoint.

Enabling the Plugin#

You can enable the batch-requests Plugin by adding it to your configuration file (conf/config.yaml):

conf/config.yaml
plugins:
- ...
- batch-requests

Configuration#

By default, the maximum body size that can be sent to /apisix/batch-requests can't be larger than 1 MiB. You can change this configuration of the Plugin through the endpoint apisix/admin/plugin_metadata/batch-requests:

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/batch-requests -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"max_body_size": 4194304
}'

Metadata#

NameTypeRequiredDefaultValid valuesDescription
max_body_sizeintegerTrue1048576[1, ...]Maximum size of the request body in bytes.

Request and response format#

This plugin will create an API endpoint in APISIX to handle batch requests.

Request#

NameTypeRequiredDefaultDescription
queryobjectFalseQuery string for the request.
headersobjectFalseHeaders for all the requests.
timeoutintegerFalse30000Timeout in ms.
pipelinearray[HttpRequest]TrueDetails of the request.

HttpRequest#

NameTypeRequiredDefaultValidDescription
versionstringFalse1.1[1.0, 1.1]HTTP version.
methodstringFalseGET["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"]HTTP method.
queryobjectFalseQuery string for the request. If set, overrides the value of the global query string.
headersobjectFalseHeaders for the request. If set, overrides the value of the global query string.
pathstringTruePath of the HTTP request.
bodystringFalseBody of the HTTP request.
ssl_verifybooleanFalsefalseSet to verify if the SSL certs matches the hostname.

Response#

The response is an array of HttpResponses.

HttpResponse#

NameTypeDescription
statusintegerHTTP status code.
reasonstringHTTP reason-phrase.
bodystringHTTP response body.
headersobjectHTTP response headers.

Specifying a custom URI#

You can specify a custom URI with the public-api Plugin.

You can set the URI you want when creating the Route and change the configuration of the public-api Plugin:

curl http://127.0.0.1:9180/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/batch-requests",
"plugins": {
"public-api": {
"uri": "/apisix/batch-requests"
}
}
}'

Example usage#

First, you need to setup a Route to the batch request API. We will use the public-api Plugin for this:

curl http://127.0.0.1:9180/apisix/admin/routes/br -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/apisix/batch-requests",
"plugins": {
"public-api": {}
}
}'

Now you can make a request to the batch request API (/apisix/batch-requests):

curl --location --request POST 'http://127.0.0.1:9080/apisix/batch-requests' \
--header 'Content-Type: application/json' \
--data '{
"headers": {
"Content-Type": "application/json",
"admin-jwt":"xxxx"
},
"timeout": 500,
"pipeline": [
{
"method": "POST",
"path": "/community.GiftSrv/GetGifts",
"body": "test"
},
{
"method": "POST",
"path": "/community.GiftSrv/GetGifts",
"body": "test2"
}
]
}'

This will give a response:

[
{
"status": 200,
"reason": "OK",
"body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
"headers": {
"Connection": "keep-alive",
"Date": "Sat, 11 Apr 2020 17:53:20 GMT",
"Content-Type": "application/json",
"Content-Length": "81",
"Server": "APISIX web server"
}
},
{
"status": 200,
"reason": "OK",
"body": "{\"ret\":500,\"msg\":\"error\",\"game_info\":null,\"gift\":[],\"to_gets\":0,\"get_all_msg\":\"\"}",
"headers": {
"Connection": "keep-alive",
"Date": "Sat, 11 Apr 2020 17:53:20 GMT",
"Content-Type": "application/json",
"Content-Length": "81",
"Server": "APISIX web server"
}
}
]

Disable Plugin#

You can remove batch-requests from your list of Plugins in your configuration file (conf/config.yaml).