API Versioning

The Brave Search API is evolving rapidly, with new iterations released all the time. However, we know that changing an existing API can be an unwelcome change, and that API developers can quickly lose flexibility as users start consuming their API. A common way to mitigate this is to add some form of versioning to the published API so users can fully rely on the API’s behavior. When you’re ready for an API change, you’ll then have an easy upgrade path forward provided by the API developers.

With Brave Search you can expect two types of versioning schemes.

1. Versioning in Request URL

The first is a major version of the format v1 that is prefixed to the API URL. An example URL will look something like this /v1/web/search. As a user you can expect this version to be rarely changed, but we reserve the right to do so. These will only be used when there is a major API redesign, which should happen only rarely, and naturally would warrant a major upgrade.

2. Versioning in Request Header

We believe in making incremental changes which are easier to digest and iterate upon for an API user. These are smaller, backwards incompatible changes, which require an upgrade path and are dated with the format YYYY-MM-DD. An API request for a product always points to the latest version available. The API behavior can be locked to a specific version by providing a version header named Api-Version as part of the request. An example version header will look something like Api-Version: 2023-01-01.

Changes made to the API can be backwards compatible or incompatible. To learn more about which changes are considered backwards compatible or incompatible, read below.

Backwards compatible changes

Brave Search considers the following changes to be backwards compatible, and they will not require action from the API user:

  • Adding new optional request parameters or headers to APIs that already exist.
  • Adding new properties to an existing API response.
  • Adding new API resources.
  • Changing the order of properties in an existing API response.
  • Changing the length and format of string values. e.g. object IDs, urls, display strings.

Backwards incompatible changes

Brave Search considers the following changes to be backwards incompatible, and they will require action from the API user (provided the API user has updated to the new API version):

  • Removing an existing request parameter or header from the API request.
  • Removing properties from an existing API response.
  • Renaming properties in an existing API response.
  • Changing the value type of properties in an existing API response.