Reference of v4 batch

arguments	description	optional
calls	A batch of endpoints defined in a json string	NO

Just like its name.
Batch api offers you a dexterity way to make api endpoints easier to interop with each other.

Tutorial 0x00

We need a piece of json string that defined the endpoints we want to request.

[
  {
    "id": 0,                     // this is an unique id
    "endpoint": "song/random"    // this is an endpoint we need to access
  }
]

Then remove all the blanks from the json.
Next, process it via the encodeURIComponent function.

Finally, we got

• %5B%7B%22id%22%3A%200%2C%22endpoint%22%3A%20%22song%2Frandom%22%7D%5D

Then add the api link ahead of the string

• https://example.com/v4/batch?calls= %5B%7B%22id%22%3A%200%2C%22endpoint%22%3A%20%22song%2Frandom%22%7D%5D

Send the request and got the result

{
    "status": 0,
    "content": [
        {
            // endpoint 0
            "id": 0,

            // the result from calling endpoint 'song/random'
            "result": {
                // endpoint status code
                "status": 0,

                // endpoint content data
                "content": {
                    "id": "altale",
                    "rating_class": 1
                }
            }
        }
    ]
}

Congratulations! You could add more endpoints to it in this way up to the BOTARCAPI_BATCH_MAX_ENDPOINTS limit.

Tutorial 0x01

This is an advanced tutorial about batch api.
Batch api introduces a funny concept named variable binding.

It's a little bit complex than tutorial 0x00.

[
  {
    "id": 0,
    "bind": {"$sid": "id"}, // ← look at this
    "endpoint": "song/random"
  },
  {
    "id": 1,                    // ↓ and $sid
    "endpoint": "song/info?songname=$sid"
  }
]

{"$sid": "id"} stored a pair of the key and value. The key "$sid" is a temporary variable we used.
The "id" is actually a javascript expression that can access the result of the current endpoint.
It cut down a lot of javascript features and syntaxes to keep context safe.

In short, The expression "id" reads the data from the current endpoint and saves the value to the "$sid" variable.
That's is the "variable binding". It's clear and easy.

Next, BotArcAPI will process the endpoints one by one and apply the variable value to the placeholder in the next endpoint url.
We suppose the "$sid" now is "grievouslady". So the endpoint

"song/info?songname=$sid"

will becomes

"song/info?songname=grievouslady"

Our variable has been applied in the next endpoint. The number of the variable binding is unlimited, So you can add more bindings into an endpoint.

Finally, The result should be

{
    "status": 0,
    "content": [
        {
            "id": 0,
            "result": {
                "status": 0,
                "content": {
                    "id": "clotho",
                    "rating_class": 0
                }
            }
        },
        {
            "id": 1,
            "result": {
                "status": 0,
                "content": {
                    "id": "clotho",
                    "title_localized": {
                        "en": "Clotho and the stargazer",
                        "ja": "クロートーと星の観測者"
                    },
                    "artist": "しーけー",
                    "bpm": "230",
                    "bpm_base": 230,
                    "set": "base",
                    "audioTimeSec": 139,
                    "side": 0,
                    "remote_dl": false,
                    "world_unlock": false,
                    "date": 1498176000,
                    "difficulties": [
                        {
                            "ratingClass": 0,
                            "chartDesigner": "小東星",
                            "jacketDesigner": "yoshimo",
                            "rating": 2,
                            "ratingReal": 2,
                            "totalNotes": 519
                        },
                        {
                            "ratingClass": 1,
                            "chartDesigner": "小東星",
                            "jacketDesigner": "yoshimo",
                            "rating": 5,
                            "ratingReal": 5,
                            "totalNotes": 745
                        },
                        {
                            "ratingClass": 2,
                            "chartDesigner": "小東星",
                            "jacketDesigner": "yoshimo",
                            "rating": 7,
                            "ratingReal": 7.5,
                            "totalNotes": 1021
                        }
                    ]
                }
            }
        }
    ]
}

Error status

status	description
0	everything is OK
-1	invalid range of start
-2	invalid range of end
-3	internal error
-4	internal error
-233	unknown error occurred