Allow api responses to be ordered #78
Conversation
Adds a new query parameter 'ordering' to the /tools GET request. Defines 3 properties that this request can be ordered by. related to #36
show how to request descending order in responses.
Add 'ordering' as a query parameter for all api endpoints.
|
@jhsimpson is the d-{order_field} a convention you've seen or used elsewhere? I've been having a quick dig around how other APIs do this and can't see an obvious consensus. I've seen sort, sortBy, orderBy among others, so I don't have a particularly strong opinion on "ordering", but I've not seen the d- elsewhere. I've seen just a negation (e.g. ?sort_by=-field), specific second parameter for direction (e.g. ?sort_by=field&order/direction=asc/desc), and combination using a separator (e.g. ?sort_by=field:asc). Given that there doesn't seem to be a particularly strong convention, I'm mostly happy as long as we're consistent, just wondering where the d- came from? |
changes the prefix used to specify 'descending' from "d-" to "-". The "d-" convention was a workaround to a bug in the typescript openapi-generator , but that bug has been fixed. Using a simple - is more common.
|
It is a fair question. The 'd-' is not a common convention. It is a workaround to a bug that used to exist in the openapi-generator that couldn't handle keys in an enum that begin with + or -. I added a commit just now to change this to using a simple '-' instead of 'd-'. I agree there isn't a single dominant convention, and I do not personally have a strong inclination to one over the other. Of the 3 examples you gave, I prefer using a '-' to indicate descending order (?ordering=foo,-bar) over the use of a separator (?ordering=foo,bar:desc) or the use of a 2nd query parameter for direction. The convention of a '-' for reverse ordering is used in Django (see for example https://medium.com/@KaziMushfiq1234/ordering-filter-in-django-rest-framework-cfe0a86adee6). |
make the description of how to order match the implementation.
api/par-api.yaml
Outdated
| - -name | ||
| - -last-modified-date |
There was a problem hiding this comment.
Are these double-hyphened repeats deliberate? It might just be outside of my experience. Every ordering param has a repeat set, am curious.
There was a problem hiding this comment.
Ahhhh, the penny drops, it's for reverse ordering...
Add a new `orderNameLastModDateParam` to support a standard way of ordering most get requests. Addresses the first half of #36
addresses the first half of #36
Adds a new query parameter to each api endpoint called 'ordering'.
Also fixes some typos in the descriptions of other query parameters.