Change notice: Deprecating /2.0/teams/ and some /2.0/users API endpoints

On October 14, 2020 all of the /2.0/teams/ and most of the /2.0/users/ API endpoints will be removed. You need to update your Bitbucket Cloud integrations to use the new /2.0/workspaces/ endpoints. These endpoints are available today, so you can start updating your code immediately.

Additionally, the owner property found in the repository, project and snippet request and response payloads will be removed. You must replace the owner property with the new workspace property, which is available now for usage and testing.

This deprecation notice details the steps you can take to update your integration and ensure a smooth transition to the workspaces-based API endpoints. Most of these changes are simple 1:1 replacements from team or user to workspace, with a few exceptions that we document below.

Why is Bitbucket making this change?

Bitbucket is making a fundamental shift from content being owned and accessed by team and user accounts, to a separation of the concerns of content hierarchy and content access. This change positions the product to align with Atlassian-wide account and team management capabilities. Atlassian-wide account management enables administrators of large organizations that use multiple Atlassian cloud products to enforce access to their content across products in a reasonable way.

What actions do you need to take as a maintainer of a Bitbucket Cloud integration?

Familiarize yourself with the previous change notice. All that advice applies as much today as when it was first written.

Overview of the breaking changes you will need to account for

• Identify users by their Bitbucket UUID or Atlassian ID (account_id). Do not use username. Support for username was dropped to comply with GDPR regulations. Learn more about that here.
• The concept of a team is going away. It is replaced for the most part by workspaces. The key difference being that teams could act as an account used to authenticate and gain access to Bitbucket. Workspaces are simple content containers.
• Along those lines, repositories, projects and snippets will no longer have an owner. They will be located within a workspace. Users will have various levels of access to the workspace. This conceptual change impacts the API response payloads for repositories, projects and snippets. The owner property will be removed.
• Furthermore, all /teams/ endpoints and most /users/ endpoints will move to /workspaces/ endpoints.
• Repository forks into a personal account will no longer occur by default.
• The representation of a user in response payloads will have its repositories and snippets links removed.
• Changes to API response payloads are also reflected in webhook payloads.

Identifying users

At first glance, this change might appear more disruptive than it actually is. It is true that username is no longer usable in URL paths. This is a technicality implemented for GDPR compliance. In actuality most users have a Workspace ID/slug that matches their username. Workspace ID/slug can still be used in the URL path. Users who are concerned with privacy can change their username or workspace ID to no longer match.

This is how you should identify a user in your code:

• uuid: This is Bitbucket-specific.
• account_id: This is a unique identifier for a user across Atlassian cloud products.

If you have both uuid and account_id, account_id is preferred.

Identifying workspaces

Workspaces can be identified by slug or UUID. The slug might be preferred because it is human readable. The UUID might be preferred because it is immutable. The slug will show up in the links section of various API response payloads that have links pointing to repositories, projects and snippets. As detailed in a previous change notice, the repository full_name field is constructed using the workspace slug.

This is how you should identify a workspace in your code.

• slug: More human friendly. Referred to as "Workspace ID" in the UI.
• uuid: Immutable.

Use the workspace section of API responses

If you previously used the owner section embedded with repository, project and snippet serializations, you should switch to using the new workspace section, because the owner section is going away.Where you might use owner.username currently, you should switch to workspace.slug. The slug will match the username unless the user has opted to change one or the other.

You might have code that looks like this in your integration:

1
2
# *** Old code ***
container = repo.owner.username

Replace this code with:

1
2
# *** New code ***
container = repo.workspace.slug

Use workspace API endpoints instead of team ones

If you access team endpoints directly (as opposed to following links in the links section of a previous API response) then replace the literal string 'teams' with 'workspaces'.

1
2
# *** Old code ***
url = '/2.0/teams/' + team.username + '/members'

Replace it with this:

1
2
# *** New code (minimal change) ***
url = '/2.0/workspaces/' + team.username + '/members'

You should also rename the variable:

1
2
# *** New code (optimal) ***
url = '/2.0/workspaces/' + workspace_slug + '/members'

Use workspace API endpoints instead of users ones

Some user endpoints will be replaced by workspaces endpoints. Those include:

• /users/{uuid}/hooks (more information on hooks below)
• /users/{uuid}/members
• /users/{uuid}/pipelines_config/variables/

To use these endpoints, follow the same instructions above. Replace users with workspaces and {uuid} with workspace_slug.

There are some endpoints that will continue to be identified by the user. For example the /2.0/pullrequests/<user> endpoint lists the pull requests authored by <user>. Workspaces don't author pull requests, so it wouldn't make sense to switch to <workspace> there. As stated above the user can be identified with their Bitbucket Cloud UUID or their Atlassian account ID.

Use repository forks API

Previously, you included the owner as part of the request body where to fork the repository. If an owner was not provided, the repository was forked by default to the personal account.

You will now need to pass a workspace in the request body. The workspace parameter is required, and we will no longer use the personal account by default. If you do not supply a workspace, you will receive an error.

1
2
# *** Old code ***
url = '/2.0/repositories/' + username + '/' + repo_slug + '/forks'
body = {
  'name': 'fork_name',
  'owner': {
    'username': 'username'
  }
}

Replace it with this:

1
2
# *** New code ***
url = '/2.0/repositories/' + workspace_slug + '/' + repo_slug + '/forks'
body = {
  'name': 'fork_name',
  'workspace': {
    'slug': 'workspace_slug'
  }
}

Caveats

Although all /2.0/teams/* endpoints will be removed, there aren't /2.0/workspaces/* replacements for every endpoint that is being removed. This section describes these exceptions.

Previously, you could get a list of repositories via /2.0/teams/{username}/repositories or /2.0/repositories/{team} which returned the same list. For workspaces, there is only one endpoint, /2.0/repositories/{workspace}. There is no /2.0/workspaces/{workspace}/repositories endpoint.

There is no replacement for /2.0/teams/followers nor /2.0/teams/following. That functionality will be removed.

Links to API docs

• /2.0/repositories/{workspace}
• /2.0/repositories/{workspace}/{repo_slug}/forks
• /2.0/workspaces/
• /2.0/workspaces/{workspace}/projects
• /2.0/snippets/{workspace}

Webhooks

Webhooks payloads are also changing and will match the new API response payloads. Mainly the owner property will be removed. The workspace property is available now. Your webhook consumers should start using the new property. The webhook documentation has been updated to reflect these changes.

Creating webhooks using the API

If your integration uses the API to create webhook definitions, you might need to update it in anticipation of the API changes. With the API you can create both repository-level and account-level webhooks.

Repository-level webhooks simply require the changes addressed in the previous change notice. Namely use the links or the full_name property instead of building the URL path using username.

The API endpoints for the managing account-level webhook definitions will move from /2.0/teams/{team}/hooks/ and /2.0/users/{user}/hooks/ to /2.0/workspaces/{workspace}/hooks. This new workspaces endpoint is available today.