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.

Tutorial 0x01

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

This means you can bind the result data from the previous endpoint
and save it to a temporary variable, then pass it to another next endpoint as the initial parameter.

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 read the data from the current endpoint result.
It cut down a lot of javascript features and syntaxes to keep context secure.

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

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

"endpoint": "song/info?songname=$sid"

will becomes

"endpoint": "song/info?songname=grievouslady"

This is not magic.

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