Early Access Toggles

• Cory Forseth

As we continue to evolve and improve the Widen Collective, we may need to change some functionality of the API. Often we can do this in a non-breaking way so existing API integrations will continue to work without any changes needed.

Sometimes, though, it’s necessary to change the behavior of endpoints in such a way that could result in unexpected behavior when handling API responses. For example:

  • a piece of data being returned in a different format
  • a different response codes being returned
  • the shape of a response changing

For changes like this, we understand that our customers need to be able to test their integrations with the new behavior before it’s enabled as the default API behavior to ensure that any consumers of the Widen API can be updated to handle the new functionality seamlessly.

To that end, we have added the ability for customers to enable these new behaviors on a per-request basis. This is done by adding custom x-widen-api-toggle headers to any requests to the API.

For example, if you get an asset by ID but want to enable some new functionality for this request:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/id' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'x-widen-api-toggle: some-new-functionality'

If needed, you can also enable multiple toggles at once using one of two methods. One option is to supply multiple X-Widen-Api-Toggle headers:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/id' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'x-widen-api-toggle: some-new-functionality' \
     --header 'x-widen-api-toggle: some-other-new-functionality'

The other option, if your client does not support multiple headers with the same name, is to supply a comma-delimited list within a single header:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/id' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'x-widen-api-toggle: some-new-functionality,some-other-new-functionality'

To support these new toggles, we’ve exposed a new API endpoint. This endpoint can be used to view a list of available early access toggles, including a test-toggle that can be used to ensure that your calls are properly enabling toggled functionality.

When we add new early access toggles, they’ll appear in the list of available toggles and be accompanied by a new post in this space detailing what will change when the toggle is enabled.

As always, if you have any questions you can reach out to our support team.