ID Range Expressions - Vanilla Success
<main> <article class="userContent"> <p>Range expressions are a powerful way to filter certain API endpoints. Usually, range expressions apply to the primary key of a resource.</p><p>A range expressions allows to you pass values in multiple ways. Let's use the <code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions</code> endpoint as an example.</p><p>The <code class="code codeInline" spellcheck="false" tabindex="0">discussionID</code> parameter on this endpoint supports range expressions.</p><h2 data-id="query-a-single-id.">Query a single ID.</h2><p>A range expression can be used to query a single ID. This example will fetch just discussion 100.</p><p><strong>Example</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=100 </pre><h2 data-id="query-an-array-of-ids">Query an array of IDs</h2><p>A fixed array of IDs may be queried with a CSV or query-string array notation. These examples will fetch discussions 100 and 150.</p><p><strong>Examples</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">// CSV notation GET /api/v2/discussions?discussionID=100,150 // Array notation GET /api/v2/discussions?discussionID[]=100&discussionID[]=150 </pre><h2 data-id="query-a-range-of-ids">Query a range of IDs</h2><p>A range of IDs may be fetched using a few different notations.</p><p><strong>Query every discussionID greater than equal to 100</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Dot notation GET /api/v2/discussions?discussionID=100.. // <= notation GET /api/v2/discussions?discussionID=>=100 // > notation GET /api/v2/discussions?discussionID=>99 </pre><p><strong>Query every discussionID less than or equal to 100</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Dot notation GET /api/v2/discussions?discussionID=..100 // >= notation GET /api/v2/discussions?discussionID=<=100 // < notation GET /api/v2/discussions?discussionID=<101 </pre><p><strong>Query a range between 100 and 150</strong></p><pre class="code codeBlock" spellcheck="false" tabindex="0">// Dot notation GET /api/v2/discussions?discussionID=100..150 // Inclusive brackets GET /api/v2/discussions?discussionID=[100,150] // Exclusive brackets GET /api/v2/discussions?discussionID=(99,151) // Mixed brackets GET /api/v2/discussions?discussionID=[100,151) </pre><h2 data-id="missing-records-with-range-expressions">Missing records with Range Expressions</h2><p>If you were to use the <code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions/100</code> and you did not have permission to access the discussion with ID 100 or it did not exist, the API would return an error code with either a permission error or a not found error.</p><p>However <code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=100</code> and <code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=(99,101)</code> will return an empty result set with no error in the same scenarios.</p><p>This is because range expressions are simply a filter on you are able to see. This makes sense if you think of the following scenario. </p><ul><li>There are 3 discussions [99, 100, 101]. </li><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=99..101</code> will return 3 results.</li><li>I delete discussion 100.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=99..101</code> will now return 2 results.</li></ul><p>It is possible and even common for there to be holes in ID ranges, so no errors are returned.</p> </article> </main>