For the latest stable version, please use Spring Data REST 4.3.5! |
Paging and Sorting
This section documents Spring Data REST’s usage of the Spring Data Repository paging and sorting abstractions. To familiarize yourself with those features, see the Spring Data documentation for the repository implementation you use (such as Spring Data JPA).
Paging
Rather than return everything from a large result set, Spring Data REST recognizes some URL parameters that influence the page size and the starting page number.
If you extend PagingAndSortingRepository<T, ID>
and access the list of all entities, you get links to the first 20 entities. To set the page size to any other number, add a size
parameter, as follows:
http://localhost:8080/people/?size=5
The preceding example sets the page size to 5.
To use paging in your own query methods, you need to change the method signature to accept an additional Pageable
parameter and return a Page
or Slice
rather than a List
. For example, the following query method is exported to /people/search/nameStartsWith
and supports paging:
@RestResource(path = "nameStartsWith", rel = "nameStartsWith")
public Page findByNameStartsWith(@Param("name") String name, Pageable p);
The Spring Data REST exporter recognizes the returned Page
/Slice
and gives you the results in the body of the response, just as it would with a non-paged response, but additional links are added to the resource to represent the previous and next pages of data.
Previous and Next Links
Each paged response returns links to the previous and next pages of results based on the current page by using the IANA-defined link relations prev
and next
. If you are currently at the first page of results, however, no prev
link is rendered. For the last page of results, no next
link is rendered.
Consider the following example, where we set the page size to 5:
curl localhost:8080/people?size=5
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons{&sort,page,size}", (1)
"templated" : true
},
"next" : {
"href" : "http://localhost:8080/persons?page=1&size=5{&sort}", (2)
"templated" : true
}
},
"_embedded" : {
… data …
},
"page" : { (3)
"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 0
}
}
At the top, we see _links
:
1 | The self link serves up the whole collection with some options. |
2 | The next link points to the next page, assuming the same page size. |
3 | At the bottom is extra data about the page settings, including the size of a page, total elements, total pages, and the page number you are currently viewing. |
When using tools such as curl on the command line, if you have a ampersand (& ) in your statement, you need to wrap the whole URI in quotation marks.
|
Note that the self
and next
URIs are, in fact, URI templates. They accept not only size
, but also page
and sort
as optional flags.
As mentioned earlier, the bottom of the HAL document includes a collection of details about the page. This extra information makes it easy for you to configure UI tools like sliders or indicators to reflect the user’s overall position when they view the data. For example, the document in the preceding example shows we are looking at the first page (with page numbers starting at 0).
The following example shows What happens when we follow the next
link:
$ curl "http://localhost:8080/persons?page=1&size=5"
{
"_links" : {
"self" : {
"href" : "http://localhost:8080/persons{&sort,projection,page,size}",
"templated" : true
},
"next" : {
"href" : "http://localhost:8080/persons?page=2&size=5{&sort,projection}", (1)
"templated" : true
},
"prev" : {
"href" : "http://localhost:8080/persons?page=0&size=5{&sort,projection}", (2)
"templated" : true
}
},
"_embedded" : {
... data ...
},
"page" : {
"size" : 5,
"totalElements" : 50,
"totalPages" : 10,
"number" : 1 (3)
}
}
This looks very similar, except for the following differences:
1 | The next link now points to yet another page, indicating its relative perspective to the self link. |
2 | A prev link now appears, giving us a path to the previous page. |
3 | The current number is now 1 (indicating the second page). |
This feature lets you map optional buttons on the screen to these hypermedia controls, letting you implement navigational features for the UI experience without having to hard code the URIs. In fact, the user can be empowered to pick from a list of page sizes, dynamically changing the content served, without having to rewrite the next
and `prev controls at the top or bottom.
Sorting
Spring Data REST recognizes sorting parameters that use the repository sorting support.
To have your results sorted on a particular property, add a sort
URL parameter with the name of the property on which you want to sort the results. You can control the direction of the sort by appending a comma (,
) to the the property name plus either asc
or desc
. The following would use the findByNameStartsWith
query method defined on the PersonRepository
for all Person
entities with names starting with the letter “K” and add sort data that orders the results on the name
property in descending order:
curl -v "http://localhost:8080/people/search/nameStartsWith?name=K&sort=name,desc"
To sort the results by more than one property, keep adding as many sort=PROPERTY
parameters as you need. They are added to the Pageable
in the order in which they appear in the query string. Results can be sorted by top-level and nested properties. Use property path notation to express a nested sort property. Sorting by linkable associations (that is, links to top-level resources) is not supported.