API v2 Overview - Vanilla Success
<main> <article class="userContent"> <p>Vanilla's <strong>API v2</strong> has been rebuilt from the ground up to enable tighter integrations and lower-level access to all of <strong>Higher Logic Vanilla's (Vanilla)</strong> features using an API-first strategy. The initial release provides feature parity with our API v1.</p><p><strong>š NOTE</strong>:Ā New endpoints will be available as they are completed, so keep an eye out for new product announcements in our <a href="https://success.vanillaforums.com/kb/docs" rel="nofollow noreferrer ugc">release notes</a>.</p><p><a href="https://docs.vanillaforums.com/api/" rel="nofollow noreferrer ugc">Looking for API v1 docs?</a></p><h3 data-id="before-we-begin...">Before we begin...</h3><p>Looking for the API v2 swagger reference? You can find it in your Dashboard (<strong>Settings > API Integrations > API V2</strong>), or in our <a href="https://success.vanillaforums.com/kb/articles/202-apiv2-reference-endpoints" rel="nofollow noreferrer ugc">full API reference.</a> Note that the reference in your Dashboard will always be more accurate and tailored to your site than the full reference.</p><h2 data-id="improvements-in-api-v2">Improvements in API v2</h2><ul><li>More authentication options, including per-user access tokens</li><li>Complete, custom API docs in your Dashboard, including examples you can use immediately</li><li>More endpoints for additional control of your site from the API</li><li>Cross-origin resource sharing (CORS) support</li><li>Greater functional consistency, and higher conformance to current industry best practices</li><li>Better automated testing to reduce regression bugs and unwanted changes</li></ul><h2 data-id="pagination">Pagination</h2><p>Vanilla uses two types of pagination in the API:</p><h4 data-id="numbered-pagination">Numbered pagination</h4><ul><li>Used where possible</li><li>Access to first, last, previous, and next pages</li></ul><h4 data-id="more-pagination">More pagination</h4><ul><li>Used where querying the totals of a particular resource would not be performant</li><li>Access to first, previous, and next pages</li></ul><p>Resources that support pagination haveĀ <code class="code codeInline" spellcheck="false" tabindex="0">page</code>Ā andĀ <code class="code codeInline" spellcheck="false" tabindex="0">limit</code>Ā parameters. For example:Ā <code class="code codeInline" spellcheck="false" tabindex="0">/api/v2/{RESOURCE}?page={PAGE_NUM}&limit={NUM_ITEMS}</code></p><p>Since the API returns an array of records, the paging information is sent using theĀ <a href="https://tools.ietf.org/html/rfc5988" rel="nofollow noreferrer ugc">Link header</a>.</p><p>Link header example:</p><pre class="code codeBlock" spellcheck="false" tabindex="0">Link: <https://forum.example.com/api/v2/users?page=1&limit=100>; rel="first", <https://forum.example.com/api/v2/users?page=5&limit=100>; rel="next" </pre><p><strong>š NOTE</strong>:Ā The example includes a line break for readability.</p><p>Depending on the pagination type, the followingĀ <code class="code codeInline" spellcheck="false" tabindex="0">rel</code>Ā values are possible:</p><ul><li><code class="code codeInline" spellcheck="false" tabindex="0">first</code> - The link relation for the <strong>first </strong>page of records.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">last</code> - The link relation for the <strong>last </strong>page of records.</li><li><code class="code codeInline" spellcheck="false" tabindex="0">prev</code> - The link relation for the immediate <strong>previous </strong>page of records.Ā <em>Only available if page > 1.</em></li><li><code class="code codeInline" spellcheck="false" tabindex="0">next</code> - The link relation for the immediate <strong>next </strong>page of records.Ā <em>Only available if more records are available.</em></li></ul><p><strong>š NOTE</strong>:Ā Results per pageĀ can be lower thanĀ the limitĀ even if more pages are available. This is due to rows being removed based on the current user's permissions. It's also possible to have empty pages for the same reason. TheĀ <code class="code codeInline" spellcheck="false" tabindex="0">Paging-Next</code>Ā header will always be present when more rows are available.</p> </article> </main>