From 4e07db0de991b2d3b6642b46555edf41c9d07cc6 Mon Sep 17 00:00:00 2001
From: Jono Yang <jyang@nexb.com>
Date: Fri, 2 Aug 2024 12:45:01 -0700
Subject: [PATCH] Update CHANGELOG.rst and api doc #508

Signed-off-by: Jono Yang <jyang@nexb.com>
---
 CHANGELOG.rst                   |  5 ++++-
 docs/source/purldb/rest_api.rst | 26 ++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 81d71149..1e2a52f6 100644
--- a/CHANGELOG.rst
+++ b/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
 ---------
diff --git a/docs/source/purldb/rest_api.rst b/docs/source/purldb/rest_api.rst
index 564a2bf3..db6c1ac3 100644
--- a/docs/source/purldb/rest_api.rst
+++ b/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
 ---------------