We have some exciting news to share: we have a major update for the Apicbase API! This marks a significant milestone since the initial release, as this version 2.0 is the first major update to the API since its initial release.

Our team has been hard at work designing, developing, testing and documenting these features to bring you a comprehensive set of changes aimed at enhancing the overall data consistency and stability of our API. While the fundamental set of features offered remains largely unchanged, we've made numerous refinements throughout that simply make sense.

This means that all endpoints have received some sort of update, be it a small tweak or a complete overhaul. The endpoint reference guides in this documentation have been updated to reflect these changes.

What's in it for you, the API user? Scroll to the bottom of this page to find answers to your main questions, but here's the short version: Immediate action is not necessary unless your operations depend on the new features introduced in Version 2. However, we encourage all users to migrate to Version 2 as soon as feasible. Going forward, Version 1 will be considered a legacy version and will receive only occasional security updates.

Your continued support and feedback have shaped this major release. Thank you for being a part of our developer community! As always, you can reach out to us at [email protected] with any eventual questions.

List of Updates

The most important changes that can break applications that switch to the new version are highlighted in bold.

Global

• The base url is now https://api.apicbase.com/api/v2/.
  • Note: the subdomain in the base URL is also changed, from app.apicbase.com to api.apicbase.com!
• Most POST endpoints with some sort of creation logic now return the 201 CREATED status code upon a successful request.
• All timestamps are now UTC, where they used to be our own local time (Brussels time). Those timestamps are indicated by a UTC timestamp marker (trailed by the character Z).
  • Note: timezone-unaware timestamps (such as in a purchase order's expected delivery date) have not changed.
• Several legacy endpoints in the library and procurement scopes that were no longer supported or documented have been dropped.
• A legacy authentication method that was no longer supported or documented was dropped. OAuth tokens are the only way to authenticate to the Apicbase API in v2.
• All references to 'VAT' have been changed to the more generic terms 'tax' and 'tax_rate'.

Accounts

• The object returned by the Get Users endpoint now contains a detailed collection of the permissions of a given user.
• The Get Outlets, Get Outlet Details, Create Outlet and Edit Outlet endpoints now require the accounts scope, instead of library.
• The outlet object returned by Get Outlets and Get Outlet Details now includes contact information for the shared supplier entity, if the outlet acts as an internal supplier.
• The detailed outlet object returned by the Get Outlet Details endpoint now includes information about entities directly linked to an outlet: recipes, ingredients, menus and suppliers.

Library

• The URL of the Get Suppliers endpoint was changed to /suppliers/.
• In the Get Suppliers endpoint, the supplier_outlet_id field points to the related outlet's ID when the supplier is an internal supplier.
• The Get Menus and Get Menu Details endpoints no longer include the deprecated 'cycle_x' fields.
• The Get Supplier Packages and Get Supplier Package endpoints now return the external supplier package IDs compatible with other endpoints.
• Dropped the deprecated 'public' field from image, recipe, ingredient and menu endpoints.
• The 'description' field was dropped from the ingredients of a recipe in the Get Recipe Details endpoint in favor of the more machine-friendly fields 'name' and 'type'.
• The Get Ingredient and Get Ingredient Details endpoints no longer include the deprecated 'gtin' field.
• The number keys used in allergen objects to indicate status (contains, does not contain, may contain...) have been replaced by string literals.
• The recipe, ingredient and menu endpoints with fields that support translations have received new attributes that list all translations in all available languages.
• In the Get Suppliers endpoint, the company_name field was renamed to name.

Inventory

• The inventory endpoints now require the new inventory scope, instead of library.
• The 'in_progress' field in all inventory event endpoints has been replaced by the 'status' field.
• Failed requets to inventory endpoints that fail a validation step will now receive a 400 BAD REQUEST response.

Sales

• The Upload Sales Data endpoint is now limited to 100 tickets in the same request.

And many, many other internal changes and cleaned-up legacy code to make our apps run more smoothly 😉

Questions and Answers

How do I know if I need to switch from Apicbase API v1 to v2?

Start by creating a list of the specific endpoints that your application currently utilizes. Take a close look at the list of changes provided above, paying special attention to the global changes, then ask yourself: Do any of these changes offer potential benefits to your operations?

If you identify changes that could positively impact your application or enhance its functionality, then it's highly recommended to make the switch to v2.

How do I know which version of the API I'm using?

It depends on the base URL you are working with: If your base URL contains "v1," you're interacting with a v1 endpoint, the default URL since the API's inception. If your base URL contains "v2," you're accessing the v2 version of that endpoint.

Keep in mind that moving forward, new endpoints will only be introduced to v2 or the current version following major updates. Those endpoints will not be reachable via a "v1" URL.

For how long will v1 remain available?

We have not determined a shutdown horizon: we plan to keep v1 available for the foreseeable future.

It's important to note that while v1 will remain accessible, no new functionalities will be introduced in this version. All v1 endpoints should now be regarded as legacy endpoints and will receive only occasional security updates.

Switching to v2 will break my code. Should I still do it?

Major releases like v2 are specifically designed to introduce breaking changes into the API. Consequently, v2 endpoints are not fundamentally backwards compatible with v1, so there is a possibility that your application will experience disruptions if you choose to make the switch.

Make sure to test every scenario thoroughly to ensure that your application functions as expected in the new environment.

However, it's vital to remember that v1 has now transitioned to a legacy version. While it will continue to function, no new features or functionalities will be introduced for v1. This implies that staying with v1 may limit your access to the latest features and improvements in the long run.

If you require any assistance or have questions about making the switch to v2, please do not hesitate to reach out to us!

I'm starting a new application using the Apicbase API, which version should I use?

You should use v2. Version 2 is not only stable but also the sole supported version at this time, so by using it, you ensure compatibility with the latest features and developments, as well as ongoing support and updates.

When will you introduce a new major version?

We do not have any scheduled major releases, including a v3, on the horizon. Our approach is to initiate a new major version only when enough breaking changes are deemed necessary, justifying its development.

In the meantime, our commitment is to regularly release new features and incremental updates to the API on a monthly basis, as we have consistently done - but those won't disrupt or break any existing code.

How do I look up documentation for a v1 endpoint?

Now that this documentation has v2 as the main version, you need to select the desired version on the dropdown available on the top left corner of the navigation bar to switch between versions.

❓

Do you still have questions? Or do you need help switching your code to the new version of the API?

Then reach out to us at [email protected].

Thank you!