Skip to main content

Using the next() function

Web Query Datasets make a single request to a Web Datasource, which returns a response that usually holds all the data the Dataset needs. Some cases need several requests in the same Dataset refresh, though, such as handling authentication tokens or paginated responses. For those, the Web Query's custom response parser can call the next() function to send a new request with a new configuration, which produces a new response.

The request config​

A request configuration describes the settings for one request. For example, take this response to a request (abridged):

{
    "status": 200,
    "statusText": "OK",
    "headers": {
        // response headers
    },
    "config": {
        "baseURL": "https://example.url.com/",
        "url": "api/v2/example-endpoint",
        "method": "get",
        "params": {},
        "headers": {
            "Accept": "application/json"
        },
        "maxContentLength": -1,
        "maxBodyLength": -1,
        "xsrfCookieName": "XSRF-TOKEN",
        "xsrfHeaderName": "X-XSRF-TOKEN"
    },
    "data": {
        "exampleParamValue": "paramValue",
        "examplePostValue": "postValue"
    }
}

The response parser reaches this object through the response variable. The config property holds the settings of the request that produced the response, and the data property holds the data the API returned. In this example, the Dataset sent a GET request, without parameters or authentication, to https://example.url.com/api/v2/example-endpoint.

Sending a follow-up request​

The simplest way to start another request is to copy the existing config object, change what you need, and pass the copy to next(). As long as the new configuration has a valid request method, base URL, and endpoint, the request goes out and returns a response. You can also add parameters or headers.

note

The response parser runs in full for every response that comes back, so always wrap a call to next() in a condition. Without one, the parser keeps calling next() and the requests never stop.

For example, if a GET request retrieves values that a follow-up POST request needs, the response parser might look like this:

if (isFirstResponse()) {
    var nextConfig = _.assign({}, response.config); // create a new config object with the same settings as the old one
    nextConfig.method = "post"; // the new request is going to use POST
    nextConfig.url = "api/v2/new-post-example-endpoint";
    nextConfig.params.newParam = response.data.exampleParamValue;
    nextConfig.data = response.data.examplePostValue;
    next(nextConfig);
}

Here the baseURL and headers properties stay as they were, because both requests share them. isFirstResponse() is the condition: it is true only for the response to the first request, so the follow-up is sent once.

What happens next​

The response to the follow-up request replaces the first response, and the response parser runs again from the start. Variables declared in the parser start over on each run, so anything you need to carry from one response to the next belongs on $local, which keeps its values for the whole refresh.

next() takes a plain object. If a run ends without calling it, no further request is sent.