Repository: netbox-community/netbox
Pull request: add example showing how to order results.
### Fixes: #15622

Fleshed out an example in the Endpoint Hierarchy documentation showing how to leverage the `ordering` parameter in a search.  Also called out the specific documentation being found in `docs/reference/filtering.md` 

Problem statement:
Add examples for ordering results to REST API documentation
### Change Type

Addition

### Area

Integrations/API

### Proposed Changes

Add a brief section on ordering to the REST API documentation, including examples. For instance,

```
GET /api/dcim/sites/?ordering=-name
```

will return all sites sorted by name in reverse alphabetical order.

Hints from issue discussion:
This is technically covered in the [docs/reference/filtering.md](https://github.com/netbox-community/netbox/blob/develop/docs/reference/filtering.md) documentation.  

I do have a slight modification based on your feedback that shows a brief example building off the filtering example under [Endpoint Hierarchy](https://github.com/netbox-community/netbox/blob/develop/docs/integrations/rest-api.md#endpoint-hierarchy).  I'd be happy to put a PR in for it.

Commit message: add example showing how to order results.

This addresses issue 15622 by building off filtering example to
show how to order results on a named field.

Patch to review:
diff --git a/docs/integrations/rest-api.md b/docs/integrations/rest-api.md
index 437f652b73d..a87ba7da39e 100644
--- a/docs/integrations/rest-api.md
+++ b/docs/integrations/rest-api.md
@@ -85,13 +85,19 @@ Each model generally has two views associated with it: a list view and a detail
 * `/api/dcim/devices/` - List existing devices or create a new device
 * `/api/dcim/devices/123/` - Retrieve, update, or delete the device with ID 123
 
-Lists of objects can be filtered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
+Lists of objects can be filtered or ordered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
 
 ```
 GET /api/dcim/interfaces/?device_id=123
 ```
 
-See the [filtering documentation](../reference/filtering.md) for more details.
+An optional `ordering` parameter can be used to define how to sort the results.  Building off the previous example, to sort all the interfaces in reverse order of creation (newest to oldest) for a device with ID 123:
+
+```
+GET /api/dcim/devices/?device_id=123&ordering=-creation
+```
+
+See the [filtering documentation](../reference/filtering.md) for more details on topics related to filtering, ordering and lookup expressions.
 
 ## Serialization
 


Code review comments:
diff_hunk: @@ -85,13 +85,19 @@ Each model generally has two views associated with it: a list view and a detail
 * `/api/dcim/devices/` - List existing devices or create a new device
 * `/api/dcim/devices/123/` - Retrieve, update, or delete the device with ID 123
 
-Lists of objects can be filtered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
+Lists of objects can be filtered or ordered using a set of query parameters. For example, to find all interfaces belonging to the device with ID 123:
 
 ```
 GET /api/dcim/interfaces/?device_id=123
 ```
 
-See the [filtering documentation](../reference/filtering.md) for more details.
+An optional `ordering` parameter can be used to define how to sort the results.  Building off the previous example, to sort all the interfaces in reverse order of creation (newest to oldest) for a device with ID 123:
+
+```
+GET /api/dcim/devices/?device_id=123&ordering=-creation
path: docs/integrations/rest-api.md
text: @user1:
The endpoint URL is incorrect for the filter, and `creation` isn't a valid filter for interfaces (it should be `created`). 

```suggestion
GET /api/dcim/interfaces/?device_id=123&ordering=-created
```