One of the major Vanilla R&D initiatives of 2017 is a brand new version version of our API. Building a new API is a priority for 2 reasons:
- Allowing our customers to better integrate with us and leverage their data, and;
- Allowing our own R&D team to be more productive.
The nature of product development results in more and more functionality being added to the product core over time. This is normal, but as the core gets larger and more complex, development can get bogged down. Eventually, developers are spending more time supporting decisions they made 5 years ago than they are building new features. At a certain point, it makes more sense to take a hard look at how the product’s technical needs have changed over time and build a sleeker, more efficient core that requires less maintenance.
We are taking an “API-first” approach for version 2, which actually means that much of Vanilla’s internals are receiving extensive re-factoring work in the process. This has already resulted in some big improvements, but it also means that we have to be extra careful about breaking backwards compatibility.
This is a major initiative, and a gating item in our product roadmap, but something that will pay serious dividends over the long term. Internally we are already building new plugins using API v2 and we hope to release a beta of the API to our customers this summer.
So, what’s changing?
1. More RESTful best practices: API v2 will bring resourceful URLs, and resources will be organized like the file and directories in a file system.
2. More secure: API v1 supports a single site-wide admin access. API v2 will allow per-user access tokens that can expire or be revoked. Further, permissions scopes on these tokens can be limited to reduce the potential damage if the token is ever compromised.
3. More endpoints and methods: More resources will be exposed including those for functionality from plugins. Currently, the API mirrors what can be done via the UI. The new API will allow for things that are not supported via the UI, such as webhooks and mass-actions.
4. Consistent formatting of output: To make your life easier, we’ll return the same formatting for the same resource regardless of which request was used. For example, the formatting of a list of discussions obtained by using GET /discussions and GET /discussions/search will be the same.
5. CORS support: We’ll be adding core support for cross-origin resource sharing (CORS) so that the API can be accessed by multiple whitelisted domains (with a sensible solution to avoid preflight requests if desired).
6. Last but not least, much better documentation: We’ll be using Open API to document the API which makes it easy to read, discover and test an API. The documentation will be available right in your Vanilla account Dashboard and will show you all available resources and methods include those available by enabling plugins.
How will existing users of the Vanilla API be impacted?
Our API v1 will continue to be supported indefinitely and can be used alongside API v2. We strongly recommend developing new integrations on API v2 once it’s available. Of note, the new API will be JSON only and won’t include support for XML which was not widely used.