List Room Admin API result ordering is not client-friendly #11759
Description
This issue has been migrated from #11759.
This came up during review of matrix-org/synapse#11737.
The List Rooms Admin API allows ordering the returned list of rooms via both order_by and dir parameters. order_by controls which room attribute to order results by, whereas dir simply allows you to reverse the ordering that is returned by the server.
The confusion stems from the default ordering of the results (before dir is applied). This ordering is either ascending or descending depending on the attribute specified by order_by. During implementation (matrix-org/synapse#6720), the intention was to provide the most "natural" sort order if you will. If ordering by room name, results would be returned ascending (a-z). If ordering by member count however, results would by default be returned in descending order (rooms with the higher member count first).
While this sounds nice in theory, when it actually comes time to implement this API from the client side, the client ends up having to maintain a lookup table of order_by parameter -> results are ascending or descending. While this information is documented in Synapse's documentation, it's potentially unnecessary work for both sides.
Ideally the sort order for all room attributes would be either ascending or descending by default. However, changing this now would be a backwards-incompatible change. There are ways to make a backwards-compatible change (such as adding additional parameters), but that would end up diverging this endpoint from the others that support pagination (whose conventions are already fairly fragmented).