GraphQL API with Bitbucket Cloud

Bitbucket Development Bitbucket Cloud
, ,
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