Confluence REST API v2: Space & Page services

Confluence Development Confluence Cloud
1

Hello everyone,

First of all, hello, if I made a mistake in some way creating an incompetent thread, I apologise.

Currently, in the project I am working on, we want to start the process of confluence api migration from version 1 to version 2. While checking the endpoints from the second version, I came across several problems regarding what the API returns, I would like to list a few points here and ask you to refer to this topic whether it will be possible to update.

1. GET - Spaces.
Currently, the application we are developing displays information about the space and the icon, what’s more, for certain places we need metadata and permissions.

Relative endpoint from REST API v2 which was tested: https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-space/#api-spaces-get

Example Object response via REST API v1:

    {
      id: 1,
      key: 'XX',
      name: 'XX,
      icon: [Object],
      description: [Object],
      type: 'global',
      metadata: [Object],
      permissions: [Array],
      status: 'current',
      _expandable: [Object],
      _links: [Object]
    },

Example Object response via REST API v2:

    {
      name: 'XX',
      key: 'XX',
      id: 1,
      type: 'global',
      homepageId: 2,
      status: 'current',
      icon: null,
      description: [Object]
    },

How You can see permissions, metadata is not received by API. Icon is always null. I’m pretty sure that permissions and metadata is not received by API because we took it from REST API v1 because of expansion, but how we can access to those data in 2 version or is there plan to include?

2. GET - Page.
Currently, the application we are developing displays HTML which is coming from Confluence into our application.

Relative endpoint from REST API v2 which was tested: https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/#api-pages-id-get

What is missing based on observations (Endpoint which we are using in REST API v1: get-content):

  • Author picture is missing
  • Author name is missing
  • History object is missing
  • Version object is not fully completed - API is receiving authorID, but what about author name, picture etc.
  • Body format view like we know from REST API v1 is not defined. We can see only storage and Atlassian docs format but it’s not a case for us. Is there any plan to introduce old format from V1? It’s possible to ask API v2 for 2 formats in one requests ?

3. Summary

I hope my questions are clear and I would like to ask for an answer.

1 Like
2

:wave: @KrystianKEDRAext

Thank you for your feedback! We are looking for any blockers for V1 → V2 migration, and these are great examples.

Hopefully the below provides some additional clarify & reassurance:

  • Space Icon → although this has not yet been documented / “officially supported” just yet, if you pass the query param include-icon=true to the V2 spaces endpoint, you should get back the space icon link
  • Space Metadata
    • In terms of labels, hopefully this answers your question (you can rest assure we are aware and working to close this gap)
    • Is there any other metadata you rely on?
  • Space Permissions → similar to the above, we are hoping to release a dedicated space permissions endpoint soon. You can test it out right now in your browser: v2/spaces/id-here/permissions
  • Author profile picture & name → Using accountId field, profile picture and name can be retrieved using V1 Get user endpoint
  • Page history / version object not complete → For V2 endpoints, we moved towards just having the versions endpoints and version details endpoints. Given this & the above V1 user endpoint for additional information about the user, is there any field that you are not able to retrieve that would be a blocker for you?
  • View format → this in the works and will be released as soon as we are able!
  • Ability to fetch multiple formats in one request → currently this is not supported, if there is enough of an ask from vendors to support this then we will be able to prioritize this work!
3

Hi @SimonKliewer,

There seems to be a change in relation to the space icon that is blocking the update of our Product to v2 APIs. I can retrieve the icon using the “include-icon=true” parameter. The returned URL is in the format:

“”/wiki/download/attachments/{entityId}/{spaceKey}?version=1&modificationDate=1658834333017&cacheVersion=1&api=v2"

With API v1, I am able to take this entityId and retrieve the corresponding attachment using this endpoint:
“/rest/api/content/{entityId}/child/attachment?spaceKey={spaceKey}”
This returns the attachment with the title of the attachment being the same as the spaceKey.

With API v2, the following requests do not work:

  1. “/api/v2/attachments?filename={spaceKey}” - returns no results
  2. “/api/v2/pages/{entityId}/attachments” - returns 404

I’m not sure if the entityId is a page Id - probably not since it returns a 404. It doesn’t appear to be possible to get the attachment ID for the space icon in v2. Am I missing something? Perhaps there should be an “/api/v2/spaces/{spaceId}/attachments” ?

Thanks!

Conor

4

Hi @ConorMacAoidh! Thanks for following up. Is there something in particular you are looking to read in besides the icon download path?

5

@SimonKliewer Yes, I want to get the attachment for the icon using the attachments endpoint. It is possible to do this in API V1. I haven’t been able to find a way to do it in API V2.

I need to get the attachment ID so that I can get a URI to download the attachment using this endpoint:
https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content---attachments/#api-wiki-rest-api-content-id-child-attachment-attachmentid-download-get

1 Like
6

Hi @ConorMacAoidh - thanks for the explanation and bringing this to our attention. We’ll work to get this blocker resolved ASAP. It can be tracked here: CONFCLOUD-76295

7

@SimonKliewer Great - thanks for following up on this and creating a ticket.

8

Now you need to reset the migration deadline to +12 months.

You cannot be forcing a migration by Jan 1st when you clearly acknowledge the lacking parity.

2 Likes
9

Hi @SimonKliewer,

May I know if there are any possibilities to include the principal’s displayName as part of the return object of the space permissions V2 API? This information used to be available in V1:

{
      "id": 1,
      "subjects": {
        "user": {
          "results": [
            {
              "type": "known",
              "accountId": "user_account_id",
              "accountType": "app",
              "email": "",
              "publicName": "Chat Notifications",
              "profilePicture": [Object],
              "displayName": "Chat Notifications",
              "isExternalCollaborator": false,
              "_expandable": [Object],
              "_links": [Object]
            }
          ],
          "size": 1
        },
      },
      "operation": {
        "operation": "create",
        "targetType": "comment"
      },
      "anonymousAccess": false,
      "unlicensedAccess": false
    },

And now there is only account ID returned by V2:

 {
      "id": "360648",
      "principal": {
        "type": "user",
        "id": "user_account_id"
      },
      "operation": {
        "key": "create",
        "targetType": "attachment"
      }
    },

While we are migrating to V2, it would be very helpful if we could get the display name as part of the return object of the V2 API without the need to call another user API with the account ID to retrieve the display name.

Any answer or advice would appreciated!

1 Like