Undocumented sort order of `Array` results from API calls

[nikclayton]

API documentation like Notifications.get (https://docs.joinmastodon.org/methods/notifications/#get) notes that the results will be returned as an Array.

The documentation does not specify whether items in this array are sorted, and if they are, what the sort order appears to be.

mastodon.social appears to return the array sorted by ID, largest (and therefore, most recent) first. But it would be helpful to make this part of the explicit API contract.

[trwnh]

results are generally sorted in reverse chronological order where applicable. i'm not sure this needs to be made explicit, though? clients can generally show results in the order provided to them.

[nikclayton]

I feel like that just opens up more questions (writing from the perspective of someone writing a client that uses the API).

"are generally sorted [...] where applicable" -- what are the situations where this is not applicable? And in those other situations, how are the results sorted (if at all).

Search results (https://docs.joinmastodon.org/entities/Search/#statuses) maybe? They are also just described as an array of Status, without specifying how that array is sorted (ID? Relevance? Username that posted them?).

"chronological order" -- what if two entries in the list have the same timestamp? Is the ordering between them random? Is it stable across multiple requests? Or if you mean that it's sorted by ID (which will stable-sort chronologically by length and content)?

"clients can generally show results in the order provided to them" -- if a server implemented the Mastodon API endpoints, but returned results in a different order, would it be considered compatible with the Mastodon API? If yes, that should be explicit so that clients can sort results to present them how they want. And if no then it should be part of the API contract.

I'm not asking those questions because I want to see the answers as replies to this issue. I'm asking them because I believe I should be able to find the answers in the API documentation, and at the moment it's not there.

[trwnh]

• i think it's pretty much just search that isn't reverse chronological, yeah.

• two entries might have the same timestamp but not the same insertion order. ordering is stable by id, which is snowflake, which is based on insertion time.

if a server implemented the Mastodon API endpoints, but returned results in a different order, would it be considered compatible with the Mastodon API?

sorr of. the complication is that the "mastodon api" is not a standard, and it was never meant to be one. there are already alternative implementations (pleroma, pixelfed, etc.) that make different choices, so the API docs try to describe what happens in practice (within reason) rather than setting an explicit contract. otherwise, you might have for example the expectation that all IDs are convertible to numbers or vice versa, which is only the case for mastodon.

tangentially, clients are not expected to do their own sorting.

I believe I should be able to find the answers in the API documentation, and at the moment it's not there.

which parts do you think should be included, and why? just a statement in the api guidelines about how ordering is done by the server, and this is generally reverse-chron within mastodon? the problem seems to be more that this issue was filed with an expectation of an "explicit API contract" which at the moment doesn't really exist. so maybe that's the real issue. there have been proposals to, for example, generate an OpenAPI definition that gets updated with every release, and serve that via some endpoint. but that requires an explicit decision by the mastodon project to formally define the API rather than have it be whatever it is.

[nikclayton]

i think it's pretty much just search that isn't reverse chronological, yeah.

So updating the docs to make this explicit shouldn't be a problem? And note that it's ordered by ID.

which parts do you think should be included, and why?

As a client developer, all the bits that a Mastodon client can expect something that claims to be a Mastodon server to follow.

And if I was a server developer, all of the bits of the API that are part of the contract that I need to follow if I want to say that my server is "Compatible with the Mastodon API".

there are already alternative implementations (pleroma, pixelfed, etc.) that make different choices,

Yes. And if they don't follow the documented Mastodon API exactly then it's a roll of the dice as to whether or not a "Mastodon client" will work correctly with them.

Pixelfed is a good example, since it is explicitliy incompatible with the Mastodon API, per https://docs.pixelfed.org/technical-documentation/api/#differences-with-mastodon-api. And Pixelfed API responses to requests that use min_id are incompatible with Mastodon's (https://github.com/tuskyapp/Tusky/issues/3580#issuecomment-1527198806).