Working with UUIDs and their curly brackets, workspace names or repository slugs in Bitbucket

[#1]

You just retrieved the response from a Bitbucket REST API and need to use the returned UUID for a subsequent request, but the documentation says that you need their name or slug (e.g. workspace name and repo_slug).

So what do you do?

Just use the UUIDs directly as-is. Keep the curly brackets as well.

For example, if you are looking for more details about a repository via the GET Get a repository REST API endpoint simply replace {workspaceUUID} and {repositoryUUID} in the URL and use https://api.bitbucket.org/2.0/repositories/{workspaceUUID}/{repositoryUUID} instead of https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug} .

How does that work when responding to a Forge trigger?

The same is true also when processing Forge triggers. The workspaceUUID and the repositoryUUID are available in the event details while the slugs are not provided.

As an example, here is what is logged as a response to a avi:bitbucket:created:pullrequest trigger:

# trigger definition in the manifest.yml
modules:
  trigger:
    - key: pullrequest-created-event
      function: main
      events:
    - avi:bitbucket:created:pullrequest

# function in the index.js
export async function prtrigger(event, context) {
console.log(`event: ${JSON.stringify(event)}`); 

The logged information:

...
"repository":{"uuid":"{e4403a47-6010-4a36-b477-117db9680f45}"}
...
"workspace":{"uuid":"{bd5ab8df-e1b9-4a2c-8d9d-156e32704c99}"}

The UUIDs can then be used directly in a subsequent request:

const res = await api
  .asApp()
  .requestBitbucket(route`/2.0/repositories/${event.workspace.uuid}/${event.repository.uuid}`);

The curly brackets have to stay

In the example above, both the event.workspace.uuid and the event.repository.uuid values are surrounded by the curly brackets.

When they are removed (e.g. with the slice method event.repository.uuid.slice(1, -1);), the requestBitbucket fails with a URL not allowed error:

URL not allowed: /2.0/repositories/bd5ab8df-e1b9-4a2c-8d9d-156e32704c99/e4403a47-6010-4a36-b477-117db9680f45

Using curl directly

A Forge app is the most powerful, while still easy, way to automate any operation in Bitbucket or to extend it. We recommend using it for any custom requirement.

However, if you are using a curl directly and receiving an error stating that The requested repository either does not exist or you do not have access and using the UUIDs in the request, you might need to encode the curly brackets so replacing { with %7B and } with %7D.

Want to check a real-life example? New to Forge?

If you would like to try this logic out in a fully working app, I’ve created this one for assigning reviewers automatically when creating a PR. The list of reviewers is in defined in each repository via a configuration file that the apps read.

And if you want to know more, Check out the documentation and the getting started example.

[keyvan zare rami]

@Caterina Curti it seems workspace UUID is compatible with Git CLI + bitbucket endpoint. Could you point me the the official doc that confirms it.  

[Caterina Curti]

@keyvan zare rami the UUID behaviour for the REST APIs is described here: https://developer.atlassian.com/cloud/bitbucket/rest/intro/#uri-uuid

You can also use the UUIDs for Git commands (e.g., cloning a repository), but I couldn't find documentation for that.

Example git clone command where the first UUID is the workspace one and the second one is the repository one:

git clone git@bitbucket.org:{574aee80-bcfb-4554-a4c9-3f5a40cde35e}/{6f5a5efa-ab96-40e5-a800-431281728a73}