GraphQL API with Bitbucket Cloud

Bitbucket Development Bitbucket Cloud
, ,
1

I’m interested in using the Atlassian GraphQL API for accessing Bitbucket Cloud data.
However, critical elements (such as an ARI lookup) seem to be missing that are present for Jira and Confluence.
For example, I would expect to be able to do something like the following:

query example {
  bitbucket {
    bitbucketWorkspace(id: "ARI") {
      name
      repositories {
        nodes {
          name
        }
      }
    }
  }
}

I don’t see how to retrieve the ARI (Confluence and Jira can use the tenantContexts, but not BB). Am I missing something obvious? Or is it not yet implemented for Bitbucket?

Thanks!

5 Likes
2

Hey @just.so did you ever figure out what is this ARI?

3

Hi @just.so, out of curiosity - what would you use the Bitbucket ARI for ?

1 Like
4

Hi @JeroenDeRaedt, that’s a slightly surprising question in context of the Atlassian Developer Community :grin:

I can’t speak for @MufaddalNalawala (welcome to the developer community btw.!) or @just.so, but given Atlassian is heavily promoting Forge, Forge is heavily using GraphQL, and the cloud developer docs are rightfully promoting the Atlassian GraphQL API as a ‘popular service’ due to being faded in as a core platform capability, I naturally prefer GraphQL over REST from Forge apps, it’s super convenient after all, not the least due to its API discovery DX.

So challenge accepted :slight_smile:

Atlassian Resource Identifiers (ARI)

You can read about ARIs in a few Atlassian blog posts, most notably:

Here are two relevant Bitbucket ARI format examples (see GraphQL queries below):

  • Repository - ari:cloud:bitbucket::repository/8dc2a048-1ff2-4eaa-81a4-b2480d80b482
  • Workspace - ari:cloud:bitbucket::workspace/2b4c816d-cf82-40b2-bfcf-af11eeb8412b

GraphQL API introspection

Here are the steps to discover your ARIs:

Get cloud ID for your Atlassian site (e.g. “ecosystem.atlassian.net”)

query getCloudId {
  tenantContexts(hostNames: ["<hostName>"]) {
    cloudId, cloudUrl, hostName, orgId
  }
}

Discover Bitbucket repository ARIs

query discoverRepositoryAris {
  bitbucketRepositoriesAvailableToLinkWithNewDevOpsService(cloudId: "<cloudId>") {
    edges {node {id, name}}
  }
}

Get workspace ID via repository ARI

query getWorkspace {
  bitbucket { 
    bitbucketRepository(id: "<repositoryId>") {
      name, workspace {id, name}}
  }
}

List repositories for workspace

query listRepositoriesForWorkspace {
  bitbucket {
    bitbucketWorkspace(id: "<workspaceId>") {
      name, repositories {nodes {id, name}}
    }
  }
}

Conclusion

Looks like that’s a good starting point to implement a Forge based Bitbucket repository browser in Jira, Confluence, or Compass - and hopefully soon also in Bitbucket itself :crossed_fingers:

Resulting ask for Atlassian

The bitbucketRepositoriesAvailableToLinkWithNewDevOpsService query is a pretty random entry for using the already available Bitbucket GraphQL queries. Instead, and that’s coming back to @just.so’s original question, it would be great to e.g. provide a findWorkspaces query to list all workspaces available to me so hat I can start from there - here’s the equivalent Confluence query for spaces:

query getSpaces {
 confluence {
    findSpaces(cloudId: "<cloudId>") {
      nodes {id, key}}
  }
}
1 Like
5

Hi @sopel,
being on the Bitbucket Cloud dev team, I am aware of ARIs - but thanks for the explanation :slight_smile:

I am more curious about the specific use case for using ARIs with regards to Bitbucket Cloud. Bitbucket is currently does not support Forge yet, so I am wondering what the end goal is?

2 Likes
6

Oh, I’m well aware of your long-time background on the Bitbucket team @JeroenDeRaedt, so thanks for engaging with the community here! I simply wanted to provide an answer for @MufaddalNalawala while at it :slight_smile:

I’ve just clarified my conclusion a bit, and as for the goal:

Many of us are hoping that Bitbucket on Forge will be available in the near future, first and foremost to provide a uniform platform across all Atlassian products, yet more importantly from a partner perspective, to hopefully unblock commercial apps for Bitbucket Cloud down the road. This has been the number one ask from the partner community almost since the inception of the Marketplace, pretty much promised for ‘next year’ ever since, yet never materialized. Given Forge apps are already Marketplace enabled as such, I’m hoping that the remaining hurdles will not be unsurmountable anymore?

Until then it would be great to unlock the Bitbucket resource graph for exploration and potential cross-product usage from inhouse Forge apps - as a (somewhat contrived) example, I realize that the Bitbucket Cloud integration for Compass does a lot more under the hood, but the workspace and repository browsing steps used during onboarding could possibly work without authentication already (after all, users do not need to separately authenticate Jira or Confluence access on their Atlassian cloud site either).

1 Like
7

Thanks for providing a bit more context @sopel :slight_smile:

Up till now, Bitbucket has been a bit hesitant to expose ARIs because the main Bitbucket REST API does not support them yet. Specifically, our concern would be that exposing ARIs would cause more confusion at this point.
Additionally, there is a chance the ARI format might change - therefor we don’t want to risk publishing something that might change.

But it is good to know that cross-product integrations are being considered and we will take this into consideration when thinking about the future of Bitbucket ARIs.
A lot of stuff is happening in the Bitbucket ecosystem space - so stay tuned!

2 Likes
8

hi,

I am trying to use requestGraph from forge to get linked bitbucket repo href as you mentioned above.

But I keep getting error:
Auth category: THIRD_PARTY_OAUTH is not allowed in service devops_service

do you know any workarounds ? or any suggestion please…

here is my code for reference:

    const CloudID = payload.context.cloudId
    const variables = { "$key1" : CloudID};
    const headers = {'Authorization': 'Bearer MMGL63Hk9JOBKkRzrKqz'};
    //const headers = {};
    const query = `query BitBucketLink ($key1 : ID!){
        bitbucketRepositoriesAvailableToLinkWithNewDevOpsService(
          cloudId: $key1
        ) {
          edges {
            node {
              href
            }
          }
        }
      }`

    const Myrequest = await api.asUser().requestGraph(query, variables, headers);