From 03535ce50b7063414dea71f753305d27506a646a Mon Sep 17 00:00:00 2001
From: jeremystretch <jstretch@ns1.com>
Date: Fri, 8 Apr 2022 16:00:33 -0400
Subject: [PATCH] Closes #8995: Enable arbitrary ordering of REST API results

---
 docs/release-notes/version-3.3.md  |  7 ++++
 docs/rest-api/filtering.md         | 20 +++++++++++
 netbox/netbox/settings.py          |  3 +-
 netbox/utilities/tests/test_api.py | 58 ++++++++++++++++++++++++++++++
 4 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 docs/release-notes/version-3.3.md

diff --git a/docs/release-notes/version-3.3.md b/docs/release-notes/version-3.3.md
new file mode 100644
index 000000000..de59d0327
--- /dev/null
+++ b/docs/release-notes/version-3.3.md
@@ -0,0 +1,7 @@
+# NetBox v3.3
+
+## v3.3.0 (FUTURE)
+
+### Enhancements
+
+* [#8995](https://github.com/netbox-community/netbox/issues/8995) - Enable arbitrary ordering of REST API results
diff --git a/docs/rest-api/filtering.md b/docs/rest-api/filtering.md
index 45dfcfa36..7ddda6f3c 100644
--- a/docs/rest-api/filtering.md
+++ b/docs/rest-api/filtering.md
@@ -106,3 +106,23 @@ expression: `n`. Here is an example of a lookup expression on a foreign key, it
 ```no-highlight
 GET /api/ipam/vlans/?group_id__n=3203
 ```
+
+## Ordering Objects
+
+To order results by a particular field, include the `ordering` query parameter. For example, order the list of sites according to their facility values:
+
+```no-highlight
+GET /api/dcim/sites/?ordering=facility
+```
+
+To invert the ordering, prepend a hyphen to the field name:
+
+```no-highlight
+GET /api/dcim/sites/?ordering=-facility
+```
+
+Multiple fields can be specified by separating the field names with a comma. For example:
+
+```no-highlight
+GET /api/dcim/sites/?ordering=facility,-name
+```
diff --git a/netbox/netbox/settings.py b/netbox/netbox/settings.py
index 04c0e9c3d..0db41373f 100644
--- a/netbox/netbox/settings.py
+++ b/netbox/netbox/settings.py
@@ -26,7 +26,7 @@ django.utils.encoding.force_text = force_str
 # Environment setup
 #
 
-VERSION = '3.2.1-dev'
+VERSION = '3.3.0-dev'
 
 # Hostname
 HOSTNAME = platform.node()
@@ -469,6 +469,7 @@ REST_FRAMEWORK = {
     ),
     'DEFAULT_FILTER_BACKENDS': (
         'django_filters.rest_framework.DjangoFilterBackend',
+        'rest_framework.filters.OrderingFilter',
     ),
     'DEFAULT_METADATA_CLASS': 'netbox.api.metadata.BulkOperationMetadata',
     'DEFAULT_PAGINATION_CLASS': 'netbox.api.pagination.OptionalLimitOffsetPagination',
diff --git a/netbox/utilities/tests/test_api.py b/netbox/utilities/tests/test_api.py
index 1171bd496..e341442be 100644
--- a/netbox/utilities/tests/test_api.py
+++ b/netbox/utilities/tests/test_api.py
@@ -176,6 +176,64 @@ class APIPaginationTestCase(APITestCase):
         self.assertEqual(len(response.data['results']), 100)
 
 
+class APIOrderingTestCase(APITestCase):
+    user_permissions = ('dcim.view_site',)
+
+    @classmethod
+    def setUpTestData(cls):
+        cls.url = reverse('dcim-api:site-list')
+
+        sites = (
+            Site(name='Site 1', slug='site-1', facility='C', description='Z'),
+            Site(name='Site 2', slug='site-2', facility='C', description='Y'),
+            Site(name='Site 3', slug='site-3', facility='B', description='X'),
+            Site(name='Site 4', slug='site-4', facility='B', description='W'),
+            Site(name='Site 5', slug='site-5', facility='A', description='V'),
+            Site(name='Site 6', slug='site-6', facility='A', description='U'),
+        )
+        Site.objects.bulk_create(sites)
+
+    def test_default_order(self):
+        response = self.client.get(self.url, format='json', **self.header)
+
+        self.assertHttpStatus(response, status.HTTP_200_OK)
+        self.assertEqual(response.data['count'], 6)
+        self.assertListEqual(
+            [s['name'] for s in response.data['results']],
+            ['Site 1', 'Site 2', 'Site 3', 'Site 4', 'Site 5', 'Site 6']
+        )
+
+    def test_order_single_field(self):
+        response = self.client.get(f'{self.url}?ordering=description', format='json', **self.header)
+
+        self.assertHttpStatus(response, status.HTTP_200_OK)
+        self.assertEqual(response.data['count'], 6)
+        self.assertListEqual(
+            [s['name'] for s in response.data['results']],
+            ['Site 6', 'Site 5', 'Site 4', 'Site 3', 'Site 2', 'Site 1']
+        )
+
+    def test_order_reversed(self):
+        response = self.client.get(f'{self.url}?ordering=-name', format='json', **self.header)
+
+        self.assertHttpStatus(response, status.HTTP_200_OK)
+        self.assertEqual(response.data['count'], 6)
+        self.assertListEqual(
+            [s['name'] for s in response.data['results']],
+            ['Site 6', 'Site 5', 'Site 4', 'Site 3', 'Site 2', 'Site 1']
+        )
+
+    def test_order_multiple_fields(self):
+        response = self.client.get(f'{self.url}?ordering=facility,name', format='json', **self.header)
+
+        self.assertHttpStatus(response, status.HTTP_200_OK)
+        self.assertEqual(response.data['count'], 6)
+        self.assertListEqual(
+            [s['name'] for s in response.data['results']],
+            ['Site 5', 'Site 6', 'Site 3', 'Site 4', 'Site 1', 'Site 2']
+        )
+
+
 class APIDocsTestCase(TestCase):
 
     def setUp(self):