Skip to main content
Version: 2.12

batch-requests

Summary#

Description#

batch-requests can accept multiple request and send them from apisix via http pipeline, and return an aggregated response to client, which can significantly improve performance when the client needs to access multiple APIs.

Tips

The HTTP headers for the outer batch request, except for the Content- headers such as Content-Type, apply to every request in the batch. If you specify a given HTTP header in both the outer request and the individual call, the header's value of individual call would override the outer batch request header's value. The headers for an individual call apply only to that call.

Attributes#

None

API#

This plugin will add /apisix/batch-requests as the endpoint. You may need to use interceptors to protect it.

How To Enable#

Enable the batch-requests plugin in the config.yaml:

# Add this in config.yaml
plugins:
- ... # plugin you need
- batch-requests

How To Configure#

By default, the maximum body size sent to the /apisix/batch-requests can't be larger than 1 MiB. You can configure it via apisix/admin/plugin_metadata/batch-requests:

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

Metadata#

NameTypeRequirementDefaultValidDescription
max_body_sizeintegerrequired1048576> 0the maximum of request body size in bytes

Batch API Request/Response#

The plugin will create a API in apisix to handle your batch request.

Batch API Request:#

NameTypeRequirementDefaultValidDescription
queryobjectoptionalSpecify QueryString for all request
headersobjectoptionalSpecify Header for all request
timeoutintegeroptional30000Aggregate API timeout in ms
pipelineHttpRequestrequiredRequest's detail

HttpRequest#

NameTypeRequirementDefaultValidDescription
versionstringoptional1.1[1.0, 1.1]http version
methodstringoptionalGET["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE"]http method
queryobjectoptionalrequest's QueryString, if Key is conflicted with global query, this setting's value will be used.
headersobjectoptionalrequest's Header, if Key is conflicted with global headers, this setting's value will be used.
pathstringrequiredhttp request's path
bodystringoptionalhttp request's body
ssl_verifybooleanoptionalfalseverify if SSL cert matches hostname.

Batch API Response:#

Response is Array of HttpResponse.

HttpResponse#

NameTypeDescription
statusintegerhttp status code
reasonstringhttp reason phrase
bodystringhttp response body
headersobjecthttp response headers

How to specify custom uri#

We can change the default uri in the plugin_attr section of conf/config.yaml.

NameTypeRequirementDefaultDescription
uristringoptional"/apisix/batch-requests"uri to use with batch-requests plugin

Here is an example:

plugin_attr:
batch-requests:
uri: "/api-gw/batch"

Test Plugin#

You can pass your request detail to batch API( /apisix/batch-requests ), apisix can automatically complete requests via http pipeline. Such as:

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"
}
]
}'

response as below:

[
{
"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#

Normally, you don't need to disable this plugin. If you do need, please make a new list of plugins you need in /conf/config.yaml to cover the original one.