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.
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.
Familiarize yourself with the previous change notice. All that advice applies as much today as when it was first written.
account_id
). Do not use username.
Support for username
was dropped to comply with GDPR regulations. Learn more about
that here.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./teams/
endpoints and most /users/
endpoints will move to /workspaces/
endpoints.repositories
and snippets
links removed.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.
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.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
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'
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.
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' } }
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.
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.
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.
Rate this page: