ID Range Expressions - Vanilla Success
<main> <article class="userContent"> <p><strong>Range expressions</strong> are a powerful way to filter certain API endpoints. Typically, they apply to the primary key of a resource.</p><ul><li>A range expression 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.</li><li>The <code class="code codeInline" spellcheck="false" tabindex="0">discussionID</code> parameter on this endpoint supports range expressions.</li></ul><h2 data-id="query-a-single-id">Query a single ID</h2><p>You can use a range expression to query a <strong>single ID</strong>. 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>You can query a fixed <strong>array of IDs</strong> 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 <strong>range of IDs</strong> may be fetched via a few notations.</p><p><strong>Query every discussionID greater 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=>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 used <code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions/100</code> but 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>Why? Because range expressions are simply a filter. This makes sense if you think of the following scenario: </p><ul><li>There are three discussions [99, 100, 101]. </li><li><code class="code codeInline" spellcheck="false" tabindex="0">GET /api/v2/discussions?discussionID=99..101</code> will return three 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 two 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>