<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:taxo="http://purl.org/rss/1.0/modules/taxonomy/" version="2.0">
  <channel>
    <title>topic Consistency of `continue` endpoint in v2 APIs in Dropbox API Support &amp; Feedback</title>
    <link>https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/Consistency-of-continue-endpoint-in-v2-APIs/m-p/491543#M24592</link>
    <description>&lt;P&gt;I've already touched upon this in &lt;A href="https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/bd-p/101000014" target="_blank" rel="noopener"&gt;my post about the search_v2 API&lt;/A&gt;, but I wanted to discuss this issue separately and in further detail.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;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 &lt;A href="https://github.com/moodle/moodle/blob/4621917c62c9634fa79927b0ed66b92a733e1498/repository/dropbox/classes/dropbox.php#L97" target="_self"&gt;see that code&lt;/A&gt; publicly on our Git repository.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Until recently, all endpoints which could return paginated results had two consistent feaures:&lt;/P&gt;&lt;UL&gt;&lt;LI&gt;They returned a `has_more` flag, and `cursor` token in the dataset; and&lt;/LI&gt;&lt;LI&gt;subsequent pages of data were available by simply appending /continue to the URI of the original endpoint&lt;/LI&gt;&lt;/UL&gt;&lt;P&gt;To give an example, you may call the `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder" target="_blank" rel="noopener"&gt;/files/list_folder&lt;/A&gt;` 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 `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue" target="_blank" rel="noopener"&gt;/files/list_folder/continue&lt;/A&gt;` endpoint with just the cursor.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;The API was entirely consistent in this approach and every endpoint implementing pagination followed the same behaviour.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;With the introduction of v2 of the search API, this changed. The search endpoint is `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-search:2" target="_blank" rel="noopener"&gt;/files/search_v2&lt;/A&gt;`, and rather than having the continue endpoint available at `/files/search_v2/continue` it is instead available at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-search:2" target="_blank" rel="noopener"&gt;/files/search/continue_v2&lt;/A&gt;`.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;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:&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;PRE&gt;if (substr($endpoint, -3) === '_v2') {
    $endpoint = substr($endpoint, 0, -3) . '/continue_v2';
}&lt;/PRE&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;However, I wouldn't be here if it were that simple.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;The `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list:1" target="_blank" rel="noopener"&gt;/list&lt;/A&gt;` API also has a v2 variant available at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list:2" target="_blank" rel="noopener"&gt;/list_v2&lt;/A&gt;`, and that also supports pagination... however the current continue endpoint is located at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list-continue" target="_blank" rel="noopener"&gt;/list/continue&lt;/A&gt;` - and there is no `_v2` in sight.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;What this means is that we now need to keep a mapping of continue endpoints for each original endpoint.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;It would be great if, for all `_v2` endpoints supporting pagination, that one (or both) of two things could be considered:&lt;/P&gt;&lt;UL&gt;&lt;LI&gt;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&lt;/LI&gt;&lt;LI&gt;include the expected pagination endpoint in the result - i.e. beside the `cursor` and `has_more` flags, include a `continue_endpoint` with value `&lt;A href="https://api.dropboxapi.com/2/files/search/continue_v2" target="_blank"&gt;https://api.dropboxapi.com/2/files/search/continue_v2&lt;/A&gt;`.&lt;/LI&gt;&lt;/UL&gt;&lt;P&gt;These changes would remove the ambiguity and create a stronger and more consistent API.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Thanks in advance,&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Andrew&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;</description>
    <pubDate>Fri, 29 Jan 2021 00:47:48 GMT</pubDate>
    <dc:creator>andrewnicols</dc:creator>
    <dc:date>2021-01-29T00:47:48Z</dc:date>
    <item>
      <title>Consistency of `continue` endpoint in v2 APIs</title>
      <link>https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/Consistency-of-continue-endpoint-in-v2-APIs/m-p/491543#M24592</link>
      <description>&lt;P&gt;I've already touched upon this in &lt;A href="https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/bd-p/101000014" target="_blank" rel="noopener"&gt;my post about the search_v2 API&lt;/A&gt;, but I wanted to discuss this issue separately and in further detail.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;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 &lt;A href="https://github.com/moodle/moodle/blob/4621917c62c9634fa79927b0ed66b92a733e1498/repository/dropbox/classes/dropbox.php#L97" target="_self"&gt;see that code&lt;/A&gt; publicly on our Git repository.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Until recently, all endpoints which could return paginated results had two consistent feaures:&lt;/P&gt;&lt;UL&gt;&lt;LI&gt;They returned a `has_more` flag, and `cursor` token in the dataset; and&lt;/LI&gt;&lt;LI&gt;subsequent pages of data were available by simply appending /continue to the URI of the original endpoint&lt;/LI&gt;&lt;/UL&gt;&lt;P&gt;To give an example, you may call the `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder" target="_blank" rel="noopener"&gt;/files/list_folder&lt;/A&gt;` 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 `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-list_folder-continue" target="_blank" rel="noopener"&gt;/files/list_folder/continue&lt;/A&gt;` endpoint with just the cursor.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;The API was entirely consistent in this approach and every endpoint implementing pagination followed the same behaviour.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;With the introduction of v2 of the search API, this changed. The search endpoint is `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-search:2" target="_blank" rel="noopener"&gt;/files/search_v2&lt;/A&gt;`, and rather than having the continue endpoint available at `/files/search_v2/continue` it is instead available at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#files-search:2" target="_blank" rel="noopener"&gt;/files/search/continue_v2&lt;/A&gt;`.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;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:&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;PRE&gt;if (substr($endpoint, -3) === '_v2') {
    $endpoint = substr($endpoint, 0, -3) . '/continue_v2';
}&lt;/PRE&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;However, I wouldn't be here if it were that simple.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;The `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list:1" target="_blank" rel="noopener"&gt;/list&lt;/A&gt;` API also has a v2 variant available at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list:2" target="_blank" rel="noopener"&gt;/list_v2&lt;/A&gt;`, and that also supports pagination... however the current continue endpoint is located at `&lt;A href="https://www.dropbox.com/developers/documentation/http/documentation#file_requests-list-continue" target="_blank" rel="noopener"&gt;/list/continue&lt;/A&gt;` - and there is no `_v2` in sight.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;What this means is that we now need to keep a mapping of continue endpoints for each original endpoint.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;It would be great if, for all `_v2` endpoints supporting pagination, that one (or both) of two things could be considered:&lt;/P&gt;&lt;UL&gt;&lt;LI&gt;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&lt;/LI&gt;&lt;LI&gt;include the expected pagination endpoint in the result - i.e. beside the `cursor` and `has_more` flags, include a `continue_endpoint` with value `&lt;A href="https://api.dropboxapi.com/2/files/search/continue_v2" target="_blank"&gt;https://api.dropboxapi.com/2/files/search/continue_v2&lt;/A&gt;`.&lt;/LI&gt;&lt;/UL&gt;&lt;P&gt;These changes would remove the ambiguity and create a stronger and more consistent API.&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Thanks in advance,&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;&lt;P&gt;Andrew&lt;/P&gt;&lt;P&gt;&amp;nbsp;&lt;/P&gt;</description>
      <pubDate>Fri, 29 Jan 2021 00:47:48 GMT</pubDate>
      <guid>https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/Consistency-of-continue-endpoint-in-v2-APIs/m-p/491543#M24592</guid>
      <dc:creator>andrewnicols</dc:creator>
      <dc:date>2021-01-29T00:47:48Z</dc:date>
    </item>
    <item>
      <title>Re: Consistency of `continue` endpoint in v2 APIs</title>
      <link>https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/Consistency-of-continue-endpoint-in-v2-APIs/m-p/491773#M24599</link>
      <description>&lt;P&gt;Thanks for the detailed writeup! I can't make any promises myself as to if/when we might work on this, but I'm bringing this up with the team.&lt;/P&gt;</description>
      <pubDate>Fri, 29 Jan 2021 16:00:21 GMT</pubDate>
      <guid>https://www.dropboxforum.com/t5/Dropbox-API-Support-Feedback/Consistency-of-continue-endpoint-in-v2-APIs/m-p/491773#M24599</guid>
      <dc:creator>Greg-DB</dc:creator>
      <dc:date>2021-01-29T16:00:21Z</dc:date>
    </item>
  </channel>
</rss>

