Sort Pattern

The Sort pattern provides sorting affordances. It often complements List and Tree patterns but can also be used to sort any resource with sortable element aspects. The Sort pattern has a Sort Info resource that describes the sorting configuration. Clients can change the sorting configuration with the Sorter resource. The elements in the resource should share the sortable properties for the Sorted resource to make sense to the client.

The client changes sort configuration by POSTing a new configuration lookup to the Sorter resource. Sorter returns the updated Sorted resource URI in its location response header.

Sorted Resource

profile: <https://level3.rest/patterns/sort#sorted-resource>

The Sorted resource can present any profile. The profile choice does not effect filtering options.

sort-info

rel="https://level3.rest/patterns/sort#sort-info"

Points to a Sort Info resource that describes the configuration of the Sorted resource’s element order.

Sort Info Resource

profile: <https://level3.rest/patterns/sort#sort-info>

The Sort Info resource describes the ordering configuration used in the Sorted resource. This configuration consists of an array of sorting declarations, which Sort Info’s representation assigns to a top-level sort-order element.

A sorting declaration in the sort-order array has these properties:

Each additional sorting declaration sub-sorts the elements by that declaration. Consider this sort order array:

{
  "sort-order": [
    { "property": "age", "direction": "descend" },
    { "property": "last-name", "direction": "ascend" }
  ]
}

The elements are sorted first by age (oldest first), and inside each age group, the elements are sorted by last-name in ascending order (alphabetical).

The XML representation looks like this:

<sort-order>
  <sort-by property="age" direction="descend"/>
  <sort-by property="last-name" direction="ascend"/>
</sort-order>

sorter

rel="https://level3.rest/patterns/sort#sorter-resource"

Points to a Sorter resource that can configure the element order of the Sorted resource.

Sorter Resource

profile: <https://level3.rest/patterns/sort#sorter-resource>

The Sorter resource changes the Sorted resource’s sort configuration. It is a Lookup resource that starts with the current configuration in its schema representation, or its template object if the lookup does not use a schema. If only a subset of the properties are sortable, then the Sorter resource should present a schema to help the client submit a successful sorting change.

A Sorter’s content is the same as the Sort Info content. Clients edit the configuration to reflect the desired sort configuration. When this new configuration is submitted to the Sorter resource, the lookup redirects to the newly-configured Sorted resource.

sorts

rel="https://level3.rest/patterns/sort#sorts"

Points to the Sorted resource that this Sorter resource configures.

© 2019-2023 Matt Bishop

This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.

Tweet about Level 3 REST