Rating sort param consistency in addons search (#20770)

* Add sort=ratings sorting param for consistency

See https://github.com/mozilla/addons-server/issues/20763

* Add test_sort_ratings search filters test

- Ensure "sort=ratings" is supported, preferred
- Ensure "sort=rating" is still supported, for backwards compatibility
- Update existing tests using "sort=rating" to use the new preferred parameter

See https://github.com/mozilla/addons-server/issues/20763

* Update addons search endpoint ratings sort documentation

Mention sort=ratings parameter being preferred.
Mention sort=rating parameter being still supported for backwards-compatibility but deprecated.
See https://github.com/mozilla/addons-server/issues/20763

* Update v5 API changelog for Addons search endpoint sort=ratings param renaming

docs/topics/api/addons.rst

@@ -53,7 +53,8 @@ This endpoint allows you to search through public add-ons.
            hotness  Hotness (average number of users progression), descending.
             random  Random ordering. Only available when no search query is
                     passed and when filtering to only return promoted add-ons.
-            rating  Bayesian rating, descending.
+           ratings  Bayesian rating, descending.
+            rating  Bayesian rating, descending (deprecated, backwards-compatibility only).
        recommended  Promoted addons in the recommended category above
                     non-recommended add-ons. Only available combined with
                     another sort - ignored on its own.

docs/topics/api/overview.rst

@@ -460,6 +460,7 @@ These are `v5` specific changes - `v4` changes apply also.
 * 2023-03-08: restricted ``lang`` parameter to only alphanumeric, ``_``, ``-``. https://github.com/mozilla/addons-server/issues/20452
 * 2023-03-09: added ``host_permissions`` to the response of the version detail endpoint. https://github.com/mozilla/addons-server/issues/20418
 * 2023-04-13: removed signing api from api/v5+ in favor of addon submission api. https://github.com/mozilla/addons-server/issues/20560
+* 2023-06-01: renamed add-ons search endpoint sort by ratings parameter to ``sort=ratings``, ``sort=rating`` is still supported for backwards-compatibility. https://github.com/mozilla/addons-server/issues/20763
 
 .. _`#11380`: https://github.com/mozilla/addons-server/issues/11380/
 .. _`#11379`: https://github.com/mozilla/addons-server/issues/11379/

src/olympia/search/filters.py

@@ -976,7 +976,10 @@ class SortingFilter(BaseFilterBackend):
         'hotness': '-hotness',
         'name': 'name.raw',
         'random': '_score',
+        # For backwards compatibility.
         'rating': '-bayesian_rating',
+        # For consistency with other filters & result properties (officially supported).
+        'ratings': '-bayesian_rating',
         'recommended': '-is_recommended',
         'relevance': '_score',
         'updated': '-last_updated',

src/olympia/search/tests/test_filters.py

@@ -199,7 +199,7 @@ class TestQueryFilter(FilterTestsBase):
 
     def test_no_rescore_if_not_sorting_by_relevance(self):
         query = 'tea pot'
-        qs = self._test_q(self._filter(data={'q': query, 'sort': 'rating'}), query)
+        qs = self._test_q(self._filter(data={'q': query, 'sort': 'ratings'}), query)
         assert 'rescore' not in qs
 
     def test_q(self):
@@ -479,13 +479,13 @@ class TestSortingFilter(FilterTestsBase):
         assert context.exception.detail == ['Invalid "sort" parameter.']
 
     def test_sort_query_multiple(self):
-        qs = self._filter(data={'sort': ['rating,created']})
+        qs = self._filter(data={'sort': ['ratings,created']})
         assert qs['sort'] == [
             self._reformat_order('-bayesian_rating'),
             self._reformat_order('-created'),
         ]
 
-        qs = self._filter(data={'sort': 'created,rating'})
+        qs = self._filter(data={'sort': 'created,ratings'})
         assert qs['sort'] == [
             self._reformat_order('-created'),
             self._reformat_order('-bayesian_rating'),
@@ -500,7 +500,7 @@ class TestSortingFilter(FilterTestsBase):
         expected = 'The "random" "sort" parameter can not be combined.'
 
         with self.assertRaises(serializers.ValidationError) as context:
-            self._filter(data={'sort': ['rating,random']})
+            self._filter(data={'sort': ['ratings,random']})
         assert context.exception.detail == [expected]
 
         with self.assertRaises(serializers.ValidationError) as context:
@@ -548,6 +548,15 @@ class TestSortingFilter(FilterTestsBase):
             {'random_score': {'seed': 737482, 'field': 'id'}}
         ]
 
+    def test_sort_ratings(self):
+        # "ratings" sort parameter is the officially supported one, for consistency.
+        qs = self._filter(data={'sort': 'ratings'})
+        assert qs['sort'] == [self._reformat_order('-bayesian_rating')]
+
+        # "rating" sort parameter is still supported for backwards compatibility.
+        qs = self._filter(data={'sort': 'rating'})
+        assert qs['sort'] == [self._reformat_order('-bayesian_rating')]
+
     def test_sort_recommended_only(self):
         # If you try to sort by just recommended it gets ignored
         qs = self._filter(data={'q': 'something', 'sort': 'recommended'})