REST API order of items in ancestors for various object types

Question

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 · Answer

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

Steve Jorgensen · Answer

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

Steve Jorgensen · Answer

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.