Skip Main Navigation
Page Content

API Switches

What do switches do?

Switches allow for the dynamic modification of Eventbrite API endpoint behaviors. They can be used to enable new or experimental features, change response formats, and other behaviors. In general, switches are used to ease the process of phasing in new API features that would otherwise break clients. Clients may activate or deactivate switchable features by setting switch headers on API requests.

Switch lifecycle

A feature and its switch go through three phases:

  1. Opt-in, in which a new switch will be available to turn on the new feature.
  2. Opt-out, in which the feature will be on by default and the switch will be available to turn it off.
  3. Fully integrated, at which time the switch will be deprecated.

Eventbrite will notify all API consumers before any switchable feature is introduced or enters a new phase.

Public and protected switches

Switches may be exposed only to certain clients, at Eventbrite’s discretion. Such switches will be restricted to a set of whitelisted API keys, and any client attempting to set a protected switch using a non-whitelisted API key will get a permission error.

Switches that are not protected are available to be used by any client.

Using switches

Making a request using switch headers

Clients use request headers to set switches on API requests. A switch header may contain any number of switch names, separated by commas. Switch names consist of letters, numbers and underscores, and are case-insensitive.

To use the example of a switch called “EVENT_FORMAT_OCT_2016” that activates a new Event serialization format:

GET /v3/events/12345/ Eb-Api-Switches-Enabled: EVENT_FORMAT_OCT_2016

This call will return the event with ID 12345 using the new format.

If the same switch were opt-out, and the client needed to make a request using the old Event format, it would deactivate the switch like so:

GET /v3/events/12345/ Eb-Api-Switches-Disabled: EVENT_FORMAT_OCT_2016

This call would return the event using the old format.

Errors

A request containing switch headers may return the following error codes:

  • 409 REQUEST_CONFLICT: Conflicting switches were passed. This happens if the client passes the same switch in both the Enabled and Disabled headers.
  • 403 NOT_AUTHORIZED: The client sent a header for a switch that it is not allowed to set.
  • 400 BAD_REQUEST: The client sent a header for a switch that does not exist or has been deprecated.

List of public switches