Update CHANGELOG.rst and api doc #508

Signed-off-by: Jono Yang <jyang@nexb.com>

CHANGELOG.rst

@@ -19,7 +19,10 @@ Next Release
   `/api/scan_queue/index_package_scan/` endpoint.
   `/api/scan_queue/update_status/` is now an action on a ScannableURI.
   https://github.com/nexB/purldb/issues/504
-
+- The packages collected via the `/api/collect/` endpoint can be ordered in an
+  ascending or descending fashion on fields using the ``sort`` query parameter.
+  This parameter takes in the same fields as ``sort`` from `/api/packages/`.
+  https://github.com/nexB/purldb/issues/508
 
 v5.0.0
 ---------

docs/source/purldb/rest_api.rst

@@ -221,6 +221,25 @@ For example:
 
     curl -X GET "$api_url?$payload" -H "$content_type"
 
+The packages list can be ordered by the following fields:
+
+    - ``type``
+    - ``namespace``
+    - ``name``
+    - ``version``
+    - ``qualifiers``
+    - ``subpath``
+    - ``download_url``
+    - ``filename``
+    - ``size``
+    - ``release_date``
+
+To sort a field in a descending fashion, prefix the field name with ``-``.
+Packages can be sorted by multiple fields.
+
+For example:
+
+``GET /api/packages/?sort=type,-size``
 
 package details
 ^^^^^^^^^^^^^^^
@@ -867,6 +886,13 @@ package. Find all addon pipelines `here. <https://scancodeio.readthedocs.io/en/l
             "history": "https://public.purldb.io/api/packages/4f3a57de-e367-43c6-a7f1-51633d0ecd45/history/"
         }
 
+The ordering of the packages returned by ``/api/collect/`` can be set using the
+``sort`` query parameter.
+
+``GET /api/collect/?purl=pkg:npm/asdf@1.0.2&sort=qualifiers,-size``
+
+The same sort fields from ``/api/packages/`` is also used here.
+
 collect actions
 ---------------
 

packagedb/tests/test_api.py

@@ -934,11 +934,6 @@ def test_collect_sort(self):
             prev_package_data = response.data[i-1]
             self.assertTrue(prev_package_data['size'] > package_data['size'])
 
-        response = self.client.get(f'/api/collect/?purl={purl_str}&sort=-size')
-        for i, package_data in enumerate(response.data[1:], start=1):
-            prev_package_data = response.data[i-1]
-            self.assertTrue(prev_package_data['size'] > package_data['size'])
-
     def test_package_api_index_packages_endpoint(self):
         priority_resource_uris_count = PriorityResourceURI.objects.all().count()
         self.assertEqual(0, priority_resource_uris_count)