BitBucket API: How to get a list of branches from a repository UUID

Question

BitBucket API so far has been an interesting experience, let's say.

We have sometimes very brief generated docs across various URLs with bits of functionality peppered between bitbucket.org/rest/api/1.0, api.bitbucket.org/2.0 etc and a way to get a list of repositories:

GET https://api.bitbucket.org/2.0/repositories?role=x

This response contains a UUID for the repo which the docs say:

This can be used as a substitute for the slug segment in URLs. Doing this guarantees your URLs will survive renaming of the repository by its owner, or even transfer of the repository to a different user.

Sounds like common sense to me! So how about getting a list of branches?

GET https://api.bitbucket.org/2.0/repositories/{username}/{repo_slug}/refs/branches

UUID can be used in place of repo_slug which is good. But it also bizarrely wants username (which can confusingly also be the org name). So the point about being resilient to moving the repository is pointless. And does the list of repositories return this? Nope.

So how, using the repository UUID, do I find out the username, or better yet get a list of branches with just the UUID which would be sensible thing to support like on GitLab/GitHub? Thanks.

Answer 1

It looks like once you have the repo UUID, you can substitute %7B%7D as an empty user/team name.

From this documentation:

Once you have the UUID for a repository you no longer need a username or team name to make the API call so long as you use an empty field.

This helps you resolve repositories no matter if the username or team name changes.

Call with team name (1team) and repository name (moxie):

curl https://api.bitbucket.org/2.0/repositories/1team/moxie

Call with UUID and empty field:

curl https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D

Call with UUID and teamname:

curl https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D