Updated URIs for avatars, attachments, and attachment thumbnails

What is changing?

In addition to the Updated URI for project avatars announcement, we’re updating the way in which avatars, attachments, and attachment thumbnails are referenced in response objects. These items will be represented by URIs for the appropriate REST API operation, rather than using non-REST URIs. These changes are to ensure that the appropriate OAuth scope checks are made when these objects are requested.

We’ve updated the following resources:

Avatar URIs

The secure/viewavatar and secure/projectavatar endpoints, which would return an avatar image matching the provided avatar ID and type, will now refer to the Get avatar image by ID API. This API requires the read:jira-work OAuth scope.

Before

{
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10000",
  "key": "MY-1",
  "fields": {
    "issuetype": {
      "name": "My issue type",
      "iconUrl": "https://your-domain.atlassian.net/secure/viewavatar?size=medium&avatarId=10100&avatarType=issuetype"
    },
    "project": {
      "name": "My project",
      "avatarUrls": {
        "48x48": "https://your-domain.atlassian.net/secure/projectavatar?pid=10000&avatarId=10200"
      }
    }
  }
}

After

{
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10000",
  "key": "MY-1",
  "fields": {
    "issuetype": {
      "name": "My issue type",
      "iconUrl": "https://your-domain.atlassian.net/rest/api/3/universal_avatar/view/type/issuetype/avatar/10100"
    },
    "project": {
      "name": "My project",
      "avatarUrls": {
        "48x48": "https://your-domain.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10200"
      }
    }
  }
}

Affected operations

The following operations referencing the secure/viewavatar resource are affected by this change:

The following operations referencing the secure/projectavatar resource are affected by this change:

Get attachment and thumbnail

Responses that include an attachment URI will now refer to the Get attachment content API. This API requires the read:jira-work OAuth scope.

Responses that include a thumbnail URI will now refer to the Get attachment thumbnail API. This API requires the read:jira-work OAuth scope.

Additionally, there are resources which currently return a prefixed URI used by Jira Service Management, e.g. /servicedesk/customershim/secure/attachment/* and /servicedesk/customershim/secure/thumbnail/*. These will also be transitioned to a new REST API which will be referenced here once the API has been finalised.

Before

{
  "id": 10000,
  "self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
  "filename": "picture.jpg",
  "content": "https://your-domain.atlassian.net/jira/secure/attachments/10000/picture.jpg",
  "thumbnail": "https://your-domain.atlassian.net/jira/secure/thumbnail/10000/picture.jpg"
}

After

{
  "id": 10000,
  "self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
  "filename": "picture.jpg",
  "content": "https://your-domain.atlassian.net/rest/api/3/attachment/content/10000",
  "thumbnail": "https://your-domain.atlassian.net/rest/api/3/attachment/thumbnail/10000"
}

Affected operations

The following operations referencing the secure/attachments and secure/thumbnail resources are affected by this change:

Why is it changing?

OAuth scopes were not being correctly enforced for app developers who were following the above resources in REST responses. Additionally there was no clear documentation available for developers who wish to consume these APIs.

What do I need to do?

If you are a developer who is following links in REST responses to request one of the above APIs, you’ll need to ensure you have declared the appropriate OAuth scope in your app descriptor. Otherwise a 403 error will be returned attempting to request the resource.

By when do I need to do it?

Changes will begin rolling out to the Jira ecosystem beta group from November 9, 2021.

These resources will be rolled out independently and we expect all APIs to reach 100% of production instances by January 14, 2022.

1 Like

Hello @Kyle,
Thanks for the announcement. Since this is a breaking change for our attachment code, I’d like to know:

  • When exactly is it being rolled out to the beta group? We haven’t seen the new format so far, even though November 9 has passed.
  • When exactly is it being rolled out to first instances outside the beta group?

We’d like to test this change extensively before getting a lot of support requests because our app is no longer working. Thanks for your help!

1 Like

Hey Ben,
In regards to the attachment API we expect the changes to be enabled for the beta group by November 17. Provided we observe a positive signal from the change we plan on commencing rollout to customers outside the beta group on November 29.

Thank you for your consideration of these changes.

2 Likes

Thanks a lot for providing the dates @Kyle! Will let you know if we experience any issues.

1 Like

Hi @ben2 , I’m one of the developers working on rolling out this change. The change for attachment URLs has been rolled out to early adopters as of start of this week. Are you seeing these changes or any issues?
Please let me know if there is any unexpected behaviour. Thanks!

1 Like

Hello @Tara, thanks a lot for the heads-up!

We can see the changed URLs in our early adopter instances and have successfully tested our app being able to handle both old and new formats. I don’t expect any further issues, but will let you know if we encounter anything unexpected.

It’s definitely an improvement that we no longer need a workaround for fetching attachments!