API Best Practices

01 Sep 2023

Concept

With VUSION Cloud, APIs are one of the key elements to the good integration of the Electronic Shelf Labels solution to your internal tools and processes.

In this document you will find our general guidelines and best practices regarding the API management.

API account set-up and management

Creating your API account

You will first need to go on https://api-portal-[env].vusion.io/signup (replace [env] by “eu” or “us”)

When setting-up your account, consider using a distribustion list email, for example vusion_api@yourcompany.com. It will guarantee that this is a future-proof account for your company, regardless of the people in charge on VUSION API developments.

To manage this account, consider doing regular reviews of the people within the distribution list, as well as password rotations.

Account and API key management

Accounts segregation

From a security perspective, we suggest having two dedicated accounts for Lab and Prod environments, example : vusion_api_lab@yourcompany.com and vusion_api@yourcompany.com

If you intend to have different dev teams working on specific use cases, you can also consider having one API account per use case.

Keys management

Once your API subscription is active, you are granted two keys per API product (go to your profile page)

Both keys are active and grant you the same rights, scope and quotas. The regeneration of a key will produce a new passphrase, and all API calls using the former passphrase will then get error responses.

To garantee the security of your data, we suggest setting up a key rotation mechanism during the development phase, so that a key can be easily regenated if a security breach occurs. This will allow you to switch from Key #1 to Key #2 without pausing your data synchronization with the VUSION Cloud platform.

Of course, never share your API keys with anyone outside of your organisation (SES-imagotag included).

API quotas & how to optimize API efficiency

Each API product for which your are granted API keys have quotas. Those quotas limit the number of calls you can do per 24h as well as the bandwidth you can use per 24h.

As soon as one of these two limits is reached, your next API calls will end up in “403 OutOfQuota” errors, preventing you to do more API calls until the total consumption of the last 24h passes below theses limits again. This delay will be clearly specified in the error response.

Example : your API quotas are 100 000 calls/24h & 1Gb/24h.

At 8am on day #1 you send 1 API call, then between 1pm and 2pm you send 99 999 API calls. The next API call that you will try to send will end up in an error 403 until 8am on day #2, and the following calls that you will try will end up in an error 403 until 1pm on day #2.

Best practices

To have the best integration with our system, some practices should be implemented on your side. Here are some insights:

Item integration

• Avoid sending unitary calls whenever possible. If you have multiple items to update, send a call with many items in the body, not one call per item.

• Batch should be limited to 5000 objects. Sending batches of 500 is a good approach

• Send only needed items data: do not send items data that will not be used on labels. For instance items that will never be sold in specific stores or items attributes that will not be displayed on the labels. You can use web-hooks to be notified for every new item-label matching so your system knows exactly which items are used in a given store. You can also query unknown items once a day to send the needed item.

• Send deltas: do not send the whole data, send only data that have changed. You don’t need to send the name and description again if the only element of the article that changed is its price.

• For store-specific data updates, targeting the full retailChainId.storeId will guarantee a faster items integration than using the retailChainId only.

Frequency

• No matter how often the data is updated on your system, you should always respect a minimum delay between 2 calls. We strongly advice against sending multiple calls per minute for a single store.

• Depending on the data and your use cases, consider applying different synchronization frequencies : prices and promotion updates must be synced ASAP between your system and VUSION Cloud, while elements like overall customer reviews and ratings can be updated only once a day.

• For big updates and/or non-urgent updates, consider sending API calls during the closing hours. This will guarantee maximum availability of the VUSION platform for daytime urgent updates.

Use of filters

“GET” queries can also consume a lot of bandwidth if not used wisely. As the labels and items data contain a lot of fields, full “GET” API calls can generate a lot of data, that will be deducted from your quotas

• Consider using filters to sort out only the fields that are needed for your queries

Retry mechanism

Retry mechanisms are a good way to ensure that all data synchonizations are done, even when the service is unavailable when you first try to send items or matchings.

Nonetheless, badly configured retry mechanisms can be penalizing for your store performance. Here are a few tips to keep in mind when developing retry mechanisms :

• Track error codes : different actions are needed depending on the error.

  • When there’s an Out of Quota error for example, there is no need to retry, it should directly trigger an alert internally

  • 429 Errors occur when too many calls are made within 100 seconds, so retrying instantly would be counter productive. The error message indicates clearly how much you have to wait (example : { "statusCode": 429, "message": "Rate limit is exceeded. Try again in 7 seconds." })

  • Another common error can be { "code": 400, "message": "Missing body" } for which a retry will not be helpful either

• Retry in a smart way : use increasing delays between retries

• Consider setting a maximum amount of retry per API call, ending in a specific queue if they still fail

Typical error codes include :

• 400 : can be due to "Missing body", "Invalid json", "Invalid item", or other specific errors related to integration errors

• 401/403 : are due to wrong API rights or proper rights without access to the store

• 403 : can also be {"statusCode": 403, "message": "Please contact your support: too much erronerous calls for [storeId] on [API URL]"}

• 403_OutOfQuota : API quotas have been reached over the last 24h, the error code is associated with the delay you have to wait before your quotas start to be replenished => "Quota will be replenished ..."

• 404 : Standard API response => Not Found - The server cannot find the requested resource

• 500 : "Internal server error", "Request Timeout after Xms", "The service is unavailable"

• 552 : Wrong storeId put in the URL

Other best practices & guidelines

Please also consider the following guidelines :

• Limit the amount of fields (name, price, description, gencode, etc.) used for your items. 50 fields per item is a good limit for all your use cases

• Limit the number of references (gencodes, EAN, internal ids) that can be used to match an item to an Electronic Shelf Label. 3 references per item is a good limit, as you can easily keep this list updated.

• The ratio between the number of items and the number of ESLs should not exceed 5, as you can easily monitor the matchings in each store and you have the tools to delete your items.

To sum up