The core functionality of Spring Data REST is to export resources for Spring Data repositories. Thus, the core artifact to look at and potentially tweak to customize the way the exporting works is the repository interface. Assume the following repository interface:
public interface OrderRepository extends CrudRepository<Order, Long> { }
For this repository, Spring Data REST exposes a collection resource
at /orders. The path is derived from the uncapitalized,
pluralized, simple class name of the domain class being managed. It also
exposes an item resource for each of the items managed by the repository
under the URI template /orders/{id}.
By default the HTTP methods to interact with these resources map to
the according methods of CrudRepository.
Read more on that in the sections on collection
resources and item resources.
For the resources exposed, we use a set of default status codes:
200 OK - for plain GET
requests.
201 Created - for POST and
PUT requests that create new resources.
204 No Content - for PUT,
PATCH, and DELETE requests if the
configuration is set to not return response bodies for resource
updates
(RepositoryRestConfiguration.returnBodyOnUpdate). If
the configuration value is set to include responses for
PUT, 200 OK will be returned for updates,
201 Created will be returned for resource created
through PUT.
A core principle of HATEOAS is that resources should be discoverable through the publication of links that point to the available resources. There are a few competing de-facto standards of how to represent links in JSON. By default, Spring Data REST uses HAL to render responses. HAL defines links to be contained in a _link property of the returned document.
Resource discovery starts at the top level of the application. By issuing a request to the root URL under which the Spring Data REST application is deployed, the client can extract a set of links from the returned JSON object that represent the next level of resources that are available to the client.
For example, to discover what resources are available at the root
of the application, issue an HTTP GET to the root
URL:
curl -v http://localhost:8080/
< HTTP/1.1 200 OK
< Content-Type: application/hal+json
{ "_links" : {
"orders" : {
"href" : "http://localhost:8080/orders"
}
}
}
The _links property of the result document is an object in itself consisting of keys representing the relation type with nested link objects as specified in HAL.
Spring Data REST exposes a collection resource named after the
uncapitalized, pluralized version of the domain class the exported
repository is handling. Both the name of the resource and the path can be
customized using the
@RepositoryRestResource on the repository
interface.
Collections resources support both GET and
POST. All other HTTP methods will cause a 405 Method
Not Allowed.
Returns all entities the repository servers through its
findAll(…) method. If the repository is a
paging repository we include the pagination links if necessary and
additional page metadata.
If the repository has pagination capabilities the resource takes the following parameters:
page - the page number to access (0 indexed,
defaults to 0).
size - the page size requested (defaults to
20).
sort - a collection of sort directives in the
format ($propertyname,)+[asc|desc]?.
405 Method Not Allowed - if the
findAll(…) methods was not exported
(through @RestResource(exported = false)) or is not
present in the repository at all.
search - a search
resource if the backing repository exposes query
methods.
Spring Data REST exposes a resource for individual collection items as sub-resources of the collection resource.
Item resources generally support GET,
PUT, PATCH and DELETE unless
explicit configuration prevents that (see below for details).
Returns a single entity.
405 Method Not Allowed - if the
findOne(…) methods was not exported
(through @RestResource(exported = false)) or is not
present in the repository at all.
For every association of the domain type we expose links named
after the association property. This can be customized by using
@RestResource on the property. The
related resources are of type association
resource.
Replaces the state of the target resource with the supplied request body.
405 Method Not Allowed - if the
save(…) methods was not exported
(through @RestResource(exported = false)) or is not
present in the repository at all.
Similar to PUT but only applying values sent with
the request body.
405 Method Not Allowed - if the
save(…) methods was not exported
(through @RestResource(exported = false)) or is not
present in the repository at all.
Spring Data REST exposes sub-resources of every item resource for
each of the associations the item resource has. The name and path of the
of the resource defaults to the name of the association property and can
be customized using @RestResource on the
association property.
Reutrns the state of the association resource
Binds the resource pointed to by the given URI(s) to the resource. This
Only supported for collection associations. Adds a new element to the collection.
The search resource returns links for all query methods exposed by a
repository. The path and name of the query method resources can be
modified using @RestResource on the method
declaration.
As the search resource is a read-only resource it supports
GET only.
Returns a list of links pointing to the individual query method resources
For every query method declared in the repository we expose a query method resource. If the resource supports pagination, the URI pointing to it will be a URI template containing the pagination parameters.
The query method resource executes the query exposed through an individual query method on the repository interface.
As the search resource is a read-only resource it supports
GET only.
Returns the result of the query execution.
If the query method has pagination capabilities (indicated in the URI template pointing to the resource) the resource takes the following parameters:
page - the page number to access (0 indexed,
defaults to 0).
size - the page size requested (defaults to
20).
sort - a collection of sort directives in the
format ($propertyname,)+[asc|desc]?.