For the latest stable version, please use Spring Data REST 4.3.5! |
Repository resources
Fundamentals
The core functionality of Spring Data REST is to export resources for Spring Data repositories. Thus, the core artifact to look at and potentially customize the way the exporting works is the repository interface. Consider 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.
Repository methods exposure
Which HTTP resources are exposed for a certain repository is mostly driven by the structure of the repository.
In other words, the resource exposure will follow which methods you have exposed on the repository.
If you extend CrudRepository
you usually expose all methods required to expose all HTTP resources we can register by default.
Each of the resources listed below will define which of the methods need to be present so that a particular HTTP method can be exposed for each of the resources.
That means, that repositories that are not exposing those methods — either by not declaring them at all or explicitly using @RestResource(exported = false)
— won’t expose those HTTP methods on those resources.
For details on how to tweak the default method exposure or dedicated HTTP methods individually see Customizing supported HTTP methods.
Default Status Codes
For the resources exposed, we use a set of default status codes:
-
200 OK
: For plainGET
requests. -
201 Created
: ForPOST
andPUT
requests that create new resources. -
204 No Content
: ForPUT
,PATCH
, andDELETE
requests when the configuration is set to not return response bodies for resource updates (RepositoryRestConfiguration.setReturnBodyOnUpdate(…)
). If the configuration value is set to include responses forPUT
,200 OK
is returned for updates, and201 Created
is returned for resource created throughPUT
.
If the configuration values (RepositoryRestConfiguration.returnBodyOnUpdate(…)
and RepositoryRestConfiguration.returnBodyCreate(…)
) are explicitly set to null
— which they are by default --, the presence of the HTTP Accept header is used to determine the response code.
Read more on this in the detailed description of collection and item resources.
Resource Discoverability
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 the links to be contained in a 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, from the returned JSON object, a set of links 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, as follows:
curl -v http://localhost:8080/
< HTTP/1.1 200 OK
< Content-Type: application/hal+json
{ "_links" : {
"orders" : {
"href" : "http://localhost:8080/orders"
},
"profile" : {
"href" : "http://localhost:8080/api/alps"
}
}
}
The property of the result document is an object that consists of keys representing the relation type, with nested link objects as specified in HAL.
For more details about the profile link, see Application-Level Profile Semantics (ALPS).
|
The Collection Resource
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 by using @RepositoryRestResource
on the repository interface.
Supported HTTP Methods
Collections resources support both GET
and POST
. All other HTTP methods cause a 405 Method Not Allowed
.
GET
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.
Methods used for invocation
The following methods are used if present (descending order):
-
findAll(Pageable)
-
findAll(Sort)
-
findAll()
For more information on the default exposure of methods, see Repository methods exposure.
Parameters
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]
?.
Custom Status Codes
The GET
method has only one custom status code:
-
405 Method Not Allowed
: If thefindAll(…)
methods were not exported (through@RestResource(exported = false)
) or are not present in the repository.
Supported Media Types
The GET
method supports the following media types:
-
application/hal+json
-
application/json
Related Resources
The GET
method supports a single link for discovering related resources:
-
search
: A search resource is exposed if the backing repository exposes query methods.
HEAD
The HEAD
method returns whether the collection resource is available. It has no status codes, media types, or related resources.
Methods used for invocation
The following methods are used if present (descending order):
-
findAll(Pageable)
-
findAll(Sort)
-
findAll()
For more information on the default exposure of methods, see Repository methods exposure.
POST
The POST
method creates a new entity from the given request body.
By default, whether the response contains a body is controlled by the Accept
header sent with the request.
If one is sent, a response body is created.
If not, the response body is empty and a representation of the resource created can be obtained by following link contained in the Location
response header.
This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnCreate(…)
accordingly.
Methods used for invocation
The following methods are used if present (descending order):
-
save(…)
For more information on the default exposure of methods, see Repository methods exposure.
The Item Resource
Spring Data REST exposes a resource for individual collection items as sub-resources of the collection resource.
Supported HTTP Methods
Item resources generally support GET
, PUT
, PATCH
, and DELETE
, unless explicit configuration prevents that (see “The Association Resource” for details).
GET
The GET
method returns a single entity.
Methods used for invocation
The following methods are used if present (descending order):
-
findById(…)
For more information on the default exposure of methods, see Repository methods exposure.
Custom Status Codes
The GET
method has only one custom status code:
-
405 Method Not Allowed
: If thefindOne(…)
methods were not exported (through@RestResource(exported = false)
) or are not present in the repository.
Supported Media Types
The GET
method supports the following media types:
-
application/hal+json
-
application/json
Related Resources
For every association of the domain type, we expose links named after the association property. You can customize this behavior by using @RestResource
on the property. The related resources are of the association resource type.
HEAD
The HEAD
method returns whether the item resource is available. It has no status codes, media types, or related resources.
Methods used for invocation
The following methods are used if present (descending order):
-
findById(…)
For more information on the default exposure of methods, see Repository methods exposure.
PUT
The PUT
method replaces the state of the target resource with the supplied request body.
By default, whether the response contains a body is controlled by the Accept
header sent with the request.
If the request header is present, a response body and a status code of 200 OK
is returned.
If no header is present, the response body is empty and a successful request returns a status of 204 No Content
.
This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnUpdate(…)
accordingly.
Methods used for invocation
The following methods are used if present (descending order):
-
save(…)
For more information on the default exposure of methods, see Repository methods exposure.
PATCH
The PATCH
method is similar to the PUT
method but partially updates the resources state.
Methods used for invocation
The following methods are used if present (descending order):
-
save(…)
For more information on the default exposure of methods, see Repository methods exposure.
Custom Status Codes
The PATCH
method has only one custom status code:
-
405 Method Not Allowed
: If thesave(…)
methods were not exported (through@RestResource(exported = false)
) or are not present in the repository.
DELETE
The DELETE
method deletes the resource exposed.
By default, whether the response contains a body is controlled by the Accept
header sent with the request.
If the request header is present, a response body and a status code of 200 OK
is returned.
If no header is present, the response body is empty and a successful request returns a status of 204 No Content
.
This behavior can be overridden by configuring RepositoryRestConfiguration.setReturnBodyOnDelete(…)
accordingly.
Methods used for invocation
The following methods are used if present (descending order):
-
delete(T)
-
delete(ID)
-
delete(Iterable)
For more information on the default exposure of methods, see Repository methods exposure.
The Association Resource
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 resource defaults to the name of the association property and can be customized by using @RestResource
on the association property.
Supported HTTP Methods
The association resource supports the following media types:
-
GET
-
PUT
-
POST
-
DELETE
PUT
The PUT
method binds the resource pointed to by the given URI(s) to the association resource (see Supported Media Types).
The Search Resource
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.
Supported HTTP Methods
As the search resource is a read-only resource, it supports only the GET
method.
GET
The GET
method returns a list of links pointing to the individual query method resources.
Supported Media Types
The GET
method supports the following media types:
-
application/hal+json
-
application/json
Related 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 is a URI template containing the pagination parameters.
The Query Method Resource
The query method resource runs the exposed query through an individual query method on the repository interface.
Supported HTTP Methods
As the query method resource is a read-only resource, it supports GET
only.
GET
The GET
method returns the result of the query.
Parameters
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]
?.