REST API order of items in ancestors for various object types

[Steve Jorgensen]

Experimentally, I am finding that for comments, the first item in the ancestors array in the response is the direct parent, but for pages, the last item in the ancestors array is the direct parent.

The API does not document the order of items in the ancestors array, so I don't know whether I am supposed to be able to rely on the order of ancestors at all. It would be nice if the API documentation can be updated to made that clear.

Of course, if the ancestors array is currently not in any guaranteed order, it would be nice if that could be changed so that the order is meaningful and is the same for all object types.

[Leonardo H]

Hello @Steve Jorgensen ,

Thanks for submitting your question to our community!

I understand that you have observed some interesting lack of pattern/standardization when retrieving information from your account over the API.

More specifically, you have found that different objects return results in different ordering, as outlined in the examples below:

• When retrieving comments, the first item in the ancestors array is the direct parent
• When retrieving pages, however, the last item is the direct parent

I'd be happy to try finding some more clarification on that for you. In order to do so, could you please share some examples of calls (endpoints and request params) you have used, to make sure we are aligned in terms of context?

• Please make sure that you do not include any sensitive information about the calls.

We appreciate your feedback in advance!

Best regards,

Leonardo H 

[Steve Jorgensen]

I have been swamped, but I do intend to provide the examples you have asked for soon.

By the way, the inconsistency is by far the lesser of my concerns as I recognize that people may have come to rely on the current behaviors in both cases. Having an official and documented way to determine the ancestor sequence in the desired direction would be most helpful though.

[Leonardo H]

Hey @Steve Jorgensen

No worries at all, I know how busy we get very often. Happy to analyze this further once I have some more context about these differences and take that feedback forward to the team!

[Steve Jorgensen]

I finally got around to collecting some API calls and results to share as an examples. In the outputs below, I have removed some of the irrelevant properties like expansions and links so they are easier to read.

First, the page ancestry:

.../wiki/rest/api/content/18776791?expand=children.page

{
 "id": "18776791",
  "type": "page",
  "status": "current",
  "title": "Dance Hall",
  "children": {
    "page": {
      "results": [
        {
          "id": "18973715",
          "type": "page",
          "status": "current",
          "title": "Front Section",
          "extensions": { "position": 1205 }
        },
        {
          "id": "18875744",
          "type": "page",
          "status": "current",
          "title": "Rear Section",
          "extensions": { "position": 1235 }
        },
        {
          "id": "18973702",
          "type": "page",
          "status": "current",
          "title": "Alcoves",
          "extensions": { "position": 2213 }
        }
      ],
      "start": 0,
      "limit": 25,
      "size": 3,
    },
  },
  "extensions": { "position": 620 }
}

.../wiki/rest/api/content/18973715?expand=children.page

{
  "id": "18973715",
  "type": "page",
  "status": "current",
  "title": "Front Section",
  "children": {
    "page": {
      "results": [
        {
          "id": "18973728",
          "type": "page",
          "status": "current",
          "title": "Soundstage",
          "extensions": { "position": 830 }
        },
        {
          "id": "18875762",
          "type": "page",
          "status": "current",
          "title": "Main Dance Floor",
          "extensions": { "position": 1771 }
        }
      ],
      "start": 0,
      "limit": 25,
      "size": 2
    }
  },
  "extensions": { "position": 1205 }
}

.../wiki/rest/api/content/18875762?expand=ancestors

{
  "id": "18875762",
  "type": "page",
  "status": "current",
  "title": "Main Dance Floor",
  "ancestors": [
    {
      "id": "18875718",
      "type": "page",
      "title": "Test Space 1 Home",
      "extensions": { "position": 630 }
    },
    {
      "id": "18776791",
      "type": "page",
      "title": "Dance Hall",
      "extensions": { "position": 620 }
    },
    {
      "id": "18973715",
      "type": "page",
      "title": "Front Section",
      "extensions": { "position": 1205 }
    }
  ],
  "extensions": { "position": 1771 }
}

Notice that the first entry in the page's ancestors array is its top-most ancestor, and the last entry is the direct parent. That's perfectly useful behavior, but if it is not documented, then I have no idea whether I can rely on it or whether it just happens to work that way right now and might change at any time and break my code.

Next, the comments:

.../wiki/rest/api/content/18875775?expand=children.comment

{
  "id": "18875775",
  "type": "comment",
  "title": "Re: Dance Hall",
  "children": {
    "comment": {
      "results": [
      {
        "id": "18809855",
        "type": "comment",
        "title": "Re: Dance Hall",
        "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
      },
      {
        "id": "18809867",
        "type": "comment",
        "status": "current",
        "title": "Re: Dance Hall",
        "macroRenderedOutput": {},
        "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
      }
    ],
    "start": 0,
    "limit": 25,
    "size": 2
    }
  },
  "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
}

.../wiki/rest/api/content/18809855?expand=children.comment

{
  "id": "18809855",
  "type": "comment",
  "title": "Re: Dance Hall",
  "children": {
    "comment": {
      "results": [
        {
          "id": "18809861",
          "type": "comment",
          "status": "current",
          "title": "Re: Dance Hall",
          "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
        }
      ],
      "start": 0,
      "limit": 25,
      "size": 1
    }
  },
  "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
}

.../wiki/rest/api/content/18809861?expand=ancestors

{
  "id": "18809861",
  "type": "comment",
  "title": "Re: Dance Hall",
  "ancestors": [
    {
    "id": "18809855",
    "type": "comment",
    "title": "Re: Dance Hall",
    "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
    },
    {
    "id": "18875775",
    "type": "comment",
    "title": "Re: Dance Hall",
    "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
    }
  ],
  "extensions": { "location": "footer", "_expandable": { "resolution": "" } }
}

Notice that the first entry in the comment's ancestors array is its direct parent, and the last entry is its top-most ancestor. Again, this perfectly useful behavior, but I don't know if the behavior is intentional or reliable since it is not documented. Also notice that it is backward to the ancestors order for pages, which is confusing.

Additionally things that would be very useful if documented and known to be reliable are things like the order of child item results and the meanings of the extensions. The order of child items seems to match the order in which pages are displayed in the UI. By design or coincidence? OK to rely on? Likewise, it appears that the order of child items can be determined by the values of the "position" extension properties, but I don't see that the meaning is actually documented anywhere.

The whole API would be much more usable with more of that kind of thing documented so we know that it is official and predictable.

[Steve Jorgensen]

See also https://community.atlassian.com/t5/Confluence-questions/Order-of-content-children-in-REST-API-response/qaq-p/2054019#U2060858

[Leonardo H]

Hello @Steve Jorgensen ,

Thanks for taking the time to grab those examples, I can now see what you meant by the order in which these elements are returned.

Moving forward, we could raise an improvement suggestion for our team to implement a consistent order for this particular element. I must say that given the real impact of implementing this change, it is unlikely that this would be implemented in a near future. 

Alternatively, documenting this would also require that we explicitly describe this element in each of the applicable endpoints. As this would not be a high priority change due to the current impact of it, the expectation is that this likely would not be updated soon.

Let me know if this would be something you would like us to proceed with. As an aside, I would also recommend that you consider sharing this question on our Developer Community, where we might get feedback from other developers currently using this.

I look forward to hearing from you again!

Regards,

Leonardo H