How to Sort JSON Server API Responses Using the _sort Query Parameter

JSON Server provides a built-in _sort query parameter that orders array resources by specified fields, supporting ascending order by default and descending order when prefixed with a minus sign (-).

The typicode/json-server package offers a zero-configuration solution for creating REST APIs from JSON files. When retrieving collections, controlling the response order is essential for pagination and user interfaces. This guide explains how to use the _sort parameter to arrange JSON Server API responses by single or multiple fields, based on the actual implementation in the source code.

How JSON Server Processes Sort Requests

Extracting the Parameter from the Request

In src/app.ts, the server extracts the _sort value from the query string and passes it to the service layer as part of the options object:

// src/app.ts:61
sort: params.get('_sort') ?? undefined,

This line retrieves the _sort parameter from the URL query string and assigns it to the sort property, which is then passed downstream to the data service.

Executing the Sort with the sort-on Library

The Service.find method in src/service.ts handles the actual sorting logic. When the sort option is present, it invokes the sort-on library, which supports comma-separated fields and nested properties:

// src/service.ts:134-136
if (opts.sort) {
  results = sortOn(results, opts.sort.split(','))
}

The sort-on library processes the comma-separated list of fields. A leading - indicates descending order, and dot notation supports nested objects (e.g., author.name).

JSON Server _sort Parameter Syntax and Examples

Ascending Sort (Default)

To sort results in ascending order, pass the field name as the value:

curl http://localhost:3000/posts?_sort=title

This orders posts alphabetically by the title field.

Descending Sort

Prefix the field name with a minus sign (-) to sort in descending order:

curl http://localhost:3000/posts?_sort=-views

This orders posts by views from highest to lowest.

Sorting by Multiple Fields

Combine multiple fields using comma-separated values. You can mix ascending and descending directions:

curl http://localhost:3000/posts?_sort=author.name,-views

This first sorts by author.name in ascending order, then by views in descending order for items with the same author.

Combining Sort with Pagination

The _sort parameter works seamlessly with pagination parameters:

curl "http://localhost:3000/posts?_sort=-createdAt&_page=2&_per_page=5"

This returns the second page of results, sorted by createdAt newest first.

Note: The _sort parameter only works on array resources (e.g., /posts). Single object endpoints (e.g., /profile) return the object as-is without sorting.

Summary

• The _sort query parameter controls the order of JSON Server API responses for array resources.
• Ascending order is the default; prefix a field with - for descending order.
• Multiple fields are supported via comma-separated values, including nested properties using dot notation (e.g., author.name).
• The implementation relies on the sort-on library, invoked in src/service.ts after parsing the parameter in src/app.ts.
• Sorting works in combination with pagination parameters like _page and _per_page.

Frequently Asked Questions

Can I sort by nested properties in JSON Server?

Yes, JSON Server supports sorting by nested properties using dot notation. For example, ?_sort=author.name sorts results by the name property within the author object. The underlying sort-on library handles the nested property access automatically.

Does the _sort parameter work on single object endpoints?

No, the _sort parameter only affects array resources such as /posts or /users. Single object endpoints like /profile return the JSON object directly without any sorting applied, as there is no array to reorder.

How do I sort in descending order?

Prefix the field name with a minus sign (-) to sort in descending order. For example, ?_sort=-views sorts by the views field from highest to lowest. You can combine ascending and descending fields in a single request using comma-separated values.

Can I sort by multiple fields with different directions?

Yes, you can specify multiple fields separated by commas, mixing ascending and descending directions as needed. For example, ?_sort=category,-price first sorts by category in ascending order, then by price in descending order within each category.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}