URL to ARI Resolution

Recommended prereading:

• Understanding ARIs — What ARIs are and how to find them
• GraphQL and Cypher — How to write Cypher queries for the Teamwork Graph API
• Call the Teamwork Graph API — Getting started with API requests

When trying to traverse the graph through a relationship in a Cypher query, it may be difficult to find an ARI (Atlassian Resource Identifier) to start the traversal.

The Teamwork Graph API has a special URL to ARI resolution feature that can be used to help with this problem

How to use it

When making a Cypher query, add a _resolveFromUrl object inside your queryParams variable. Each key is the parameter name you want to use in your Cypher query, and the value is the URL you want resolved.

Here's a complete example. Say you want to find out who is assigned to a Jira issue, and all you have is the issue URL:

GraphQL query:

1
2
query FindAssignee($cypherQuery: String!, $queryParams: CypherRequestParams) {
  cypherQuery(query: $cypherQuery, params: $queryParams) {
    edges {
      node {
        columns {
          value {
            ... on CypherQueryResultNode {
              id
              data {
                __typename
                ... on AtlassianUser {
                  name
                  email
                }
              }
            }
          }
        }
      }
    }
  }
}

Variables:

1
2
{
  "cypherQuery": "MATCH (issue:JiraIssue {ari: $issueId})<-[:atlassian_user_assigned_jira_work_item]-(user:AtlassianUser) RETURN user",
  "queryParams": {
    "_resolveFromUrl": {
      "issueId": "https://mysite.atlassian.net/browse/PROJ-123"
    }
  }
}

That's it. The API takes the URL https://mysite.atlassian.net/browse/PROJ-123, resolves it to the issue's ARI behind the scenes, and runs your Cypher query as if you had passed the ARI directly.

Mixing URLs and ARIs

If you already have an ARI for one parameter but a URL for another, you can mix them. Parameters outside of _resolveFromUrl are passed through as-is:

1
2
{
  "cypherQuery": "MATCH (user:AtlassianUser {ari: $userId})-[:atlassian_user_assigned_jira_work_item]->(issue:JiraIssue {ari: $issueId}) RETURN issue",
  "queryParams": {
    "userId": "ari:cloud:identity::user/712020:c61e48fc-3803-42f7-95e9-91b5074843f3",
    "_resolveFromUrl": {
      "issueId": "https://mysite.atlassian.net/browse/PROJ-123"
    }
  }
}

What URLs are supported?

You can pass URLs for a wide range of Atlassian and third-party resources. Here are the currently supported types:

If a URL isn't in a supported format, the API won't block your query — it will skip that parameter and include a warning in the response (see below).

What happens when a URL can't be resolved?

The API uses a partial success approach. If one URL fails to resolve, the rest of your query still runs with whatever parameters did resolve successfully. You'll get a warning in the errors array of the response telling you which URL failed and why.

For example, if you accidentally pass an unsupported URL:

1
2
{
  "errors": [
    {
      "message": "Failed to resolve URL 'https://www.google.com' for parameter 'param2': URL is not supported (status: 404). Query continues with successful resolutions.",
      "extensions": {
        "parameterName": "param2",
        "url": "https://www.google.com",
        "errorType": "ResolveURLError",
        "statusCode": 404
      }
    }
  ],
  "data": {
    "cypherQuery": {
      "edges": [ ... ]
    }
  }
}

Your query still returns data for the parameters that resolved successfully — it doesn't fail entirely just because one URL couldn't be resolved.