Consistency of `continue` endpoint in v2 APIs

I've already touched upon this in my post about the search_v2 API, but I wanted to discuss this issue separately and in further detail.

For our implementation of the Dropbox API, at Moodle we have a function which fetches results from an endpoint using supplied parameters, handles error checking of the response, and also handles pagination. You can see that code publicly on our Git repository.

Until recently, all endpoints which could return paginated results had two consistent feaures:

• They returned a `has_more` flag, and `cursor` token in the dataset; and
• subsequent pages of data were available by simply appending /continue to the URI of the original endpoint

To give an example, you may call the `/files/list_folder` endpoint passing it a path, and some parameters. The response may include multiple pages of results, so the `has_more` flag would be set to true and a cursor would be included. Knowing this you could then append `continue` to the URI and simply call the the `/files/list_folder/continue` endpoint with just the cursor.

The API was entirely consistent in this approach and every endpoint implementing pagination followed the same behaviour.

With the introduction of v2 of the search API, this changed. The search endpoint is `/files/search_v2`, and rather than having the continue endpoint available at `/files/search_v2/continue` it is instead available at `/files/search/continue_v2`.

Whilst only a simple change at first glance, it is a break from the previously strong consistency of the old API. Initially it seems like a reasonably easy change - for v2 API endpoints, detect the presence of `_v2` at the end of the URI, strip it off, append `continue`, and append the `_v2` back again. In PHP It'd be something like:

if (substr($endpoint, -3) === '_v2') {
    $endpoint = substr($endpoint, 0, -3) . '/continue_v2';
}

However, I wouldn't be here if it were that simple.

The `/list` API also has a v2 variant available at `/list_v2`, and that also supports pagination... however the current continue endpoint is located at `/list/continue` - and there is no `_v2` in sight.

What this means is that we now need to keep a mapping of continue endpoints for each original endpoint.

It would be great if, for all `_v2` endpoints supporting pagination, that one (or both) of two things could be considered:

• have the `continue` endpoint consistently named in the same was as before - i.e. provide a `/list_v2/continue` and `/files/search_v2/continue` endpoint (or an alias of the the `/files/search/continue_v2` endpoint); and/or
• include the expected pagination endpoint in the result - i.e. beside the `cursor` and `has_more` flags, include a `continue_endpoint` with value `https://api.dropboxapi.com/2/files/search/continue_v2`.

These changes would remove the ambiguity and create a stronger and more consistent API.

Thanks in advance,

Andrew