Inconsistency in rating sort & filter query parameters (original) (raw)

Describe the problem and steps to reproduce it:

On the /api/v5/addons/search API endpoint, one can filter & sort add-ons by rating.
For example, a query used for searching add-ons with an average rating of 4 and sorting the results by rating would like this:

• /api/v5/addons/search/?ratings__gte=4&sort=rating

What happened?

The query parameters for filtering & sorting add-ons by ratings aren't named consistently which can be confusing & error-prone, especially since, in the endpoint documentation, sort parameters & threshold style filter parameters are presented next to each other.

View docs screenshot

What did you expect to happen?

The ratings related object property & sort/filter query parameters should be named consistently.

Anything else we should know?

ratings being the property actually returned in the addon details object, it might be preferable to:

• support the sort=ratings query parameter.
• keep the sort=rating query parameter as an alias.
• update documentation to mention only sort=ratings query parameter for consistency / DX.
• make the "sorting parameters" & "threshold style filtering parameters" sections in the endpoint documentation stand out more from each other.

Additionally, glancing at src/olympa/search/filters.py, it appears the filtering & sorting logic currently do not leverage the same ratings field: the ratings filter relies on the ratings.average field, whereas the rating sort relies on bayesian_rating, which might or might not be intentional, may lead to odd behavior.

┆Issue is synchronized with this Jira Task