Spring Data REST is itself a Spring MVC application and is designed in such a way that it should integrate with your existing Spring MVC applications with very little effort. An existing (or future) layer of services can run alongside Spring Data REST with only minor considerations.

The simplest way to get to started is if you are building a Spring Boot application. That’s because Spring Data REST has both a starter as well as auto-configuration.

When using Spring Boot, Spring Data REST gets configured automatically.

To add Spring Data REST to a Gradle-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies:

To add Spring Data REST to a Maven-based project, add the spring-data-rest-webmvc artifact to your compile-time dependencies:

To install Spring Data REST alongside your existing Spring MVC application, you need to include the appropriate MVC configuration. Spring Data REST configuration is defined in a class called RepositoryRestMvcConfiguration and that class can just be imported into your applications configuration.

To customize the configuration, register a RepositoryRestConfigurer (or extend RepositoryRestConfigurerAdapter) and implement or override the configure…-methods relevant to your use case.

Make sure you also configure Spring Data repositories for the store you use. For details on that, please consult the reference documentation for the corresponding Spring Data module.

At this point, you must also configure your key data store.

Spring Data REST officially supports:

Here are some Getting Started guides to help you get up and running quickly:

These linked guides introduce how to add dependencies for the related data store, configure domain objects, and define repositories.

You can run your application as either a Spring Boot app (with links showns above) or configure it as a classic Spring MVC app.

From this point, you can are free to customize Spring Data REST with various options.

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:

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.

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.

Spring Data REST exposes a resource for individual collection items as sub-resources of the collection 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 of the resource defaults to the name of the association property and can be customized using @RestResource on the association property.

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.

The query method resource executes the query exposed through an individual query method on the repository interface.

Rather than return everything from a large result set, Spring Data REST recognizes some URL parameters that will influence the page size and starting page number.

If you extend PagingAndSortingRepository<T, ID> and access the list of all entities, you’ll get links to the first 20 entities. To set the page size to any other number, add a size parameter:

This will set 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 rather than a List. For example, the following query method will be exported to /people/search/nameStartsWith and will support paging:

The Spring Data REST exporter will recognize the returned Page and give you the results in the body of the response, just as it would with a non-paged response, but additional links will be added to the resource to represent the previous and next pages of data.

Spring Data REST recognizes sorting parameters that will 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 you want to sort the results on. You can control the direction of the sort by appending a , 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:

To sort the results by more than one property, keep adding as many sort=PROPERTY parameters as you need. They will be added to the Pageable in the order 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 (i.e. resources to top-level resources) is not supported.

Spring Data REST returns a representation of a domain object that corresponds to the requested Accept type specified in the HTTP request.

Currently, only JSON representations are supported. Other representation types can be supported in the future by adding an appropriate converter and updating the controller methods with the appropriate content-type.

Sometimes the behavior of the Spring Data REST’s ObjectMapper, which has been specially configured to use intelligent serializers that can turn domain objects into links and back again, may not handle your domain model correctly. There are so many ways one can structure your data that you may find your own domain model isn’t being translated to JSON correctly. It’s also sometimes not practical in these cases to try and support a complex domain model in a generic way. Sometimes, depending on the complexity, it’s not even possible to offer a generic solution.

Look at the following domain model:

This Person has several attributes:

Now assume we create a corresponding repository as follows:

By default, Spring Data REST will export this domain object including all of its attributes. firstName and lastName will be exported as the plain data objects that they are. There are two options regarding the address attribute. One option is to also define a repository for Address objects like this:

In this situation, a Person resource will render the address attribute as a URI to it’s corresponding Address resource. If we were to look up "Frodo" in the system, we could expect to see a HAL document like this:

There is another route. If the Address domain object does not have it’s own repository definition, Spring Data REST will inline the data fields right inside the Person resource.

But what if you don’t want address details at all? Again, by default, Spring Data REST will export all its attributes (except the id). You can offer the consumer of your REST service an alternative by defining one or more projections.

This projection has the following details:

The NoAddresses projection only has getters for firstName and lastName meaning that it won’t serve up any address information. Assuming you have a separate repository for Address resources, the default view from Spring Data REST is slightly different as shown below:

To view apply the projection to the resource, look up http://localhost:8080/persons/1?projection=noAddresses.

It’s possible to have multiple projections.

How does Spring Data REST finds projection definitions?

In either situation, the interface with your projection MUST have the @Projection annotation.

An excerpt is a projection that is applied to a resource collection automatically. For an example, you can alter the PersonRepository as follows:

This directs Spring Data REST to use the NoAddresses projection when embedding Person resources into collections or related resources.

In addition to altering the default rendering, excerpts have additional rendering options as shown below.

A common situation with REST services arises when you compose domain objects. For example, a Person is stored in one table and their related Address is stored in another. By default, Spring Data REST will serve up the person’s address as a URI the client must navigate. But if it’s common for consumers to always fetch this extra piece of data, an excerpt projection can go ahead and inline this extra piece of data, saving you an extra GET. To do so, let’s define another excerpt projection:

We can plug it into the PersonRepository definition as follows:

This will cause the HAL document to appear as follows:

This should appear as a mix of what you’ve seen so far.

The ETag header provides a way to tag resources. This can prevent clients from overriding each other while also making it possible to reduce unnecessary calls.

This POJO, when served up as a REST resource by Spring Data REST, will have an ETag header with the value of the version field.

We can conditionally PUT, PATCH, or DELETE that resource if we supply a If-Match header like this:

Only if the resource’s current ETag state matches this If-Match header will the operation be carried out. This prevents clients from stomping on each other. Two different clients can fetch the resource and have an identical ETag. If one client updates the resource, it will get a new ETag in the response. But the first client still has the old header. If that client attempts an update with the If-Match header, the update will fail because they no longer match. Instead, that client will receive an HTTP 412 Precondition Failed message to be sent back. The client can then catch up however is necessary.

The If-None-Match header provides an alternative. Instead of conditional updates, If-None-Match allow conditional queries.

This command (by default) executes a GET. Spring Data REST will check for If-None-Match headers while doing a GET. If the header MATCHES the ETag, it will conclude nothing has changed, and instead of sending a copy of the resource, instead send back an HTTP 304 Not Modified status code. Semantically, it reads "If this supplied header value doesn’t match the server-side version, then send me the whole resource, otherwise, don’t send me anything."

The If-Modified-Since header provides a way to check if a resource has been updated since the last request to avoid resending the same data.

With this field, Spring Data REST will return a Last-Modified header like this:

This value can be capture and used for subsequent queries to avoid fetching the same data twice if it hasn’t been updated.

With this simple command, you are asking that a resource only be fetched if it’s changed since that time. If so, you will get a revised Last-Modified header to update the client. If not, you will receive an HTTP 304 Not Modified status code.

The header is perfectly formatted to send back for a future query.

ETags combined with the If-Match and If-None-Match headers empower you to build frontend that is more friendly to consumer’s data plans and mobile battery lives.

By embedding ETags and Last-Modified values into your DOM (or perhaps elsewhere for a native mobile app), you can then reduce the consumption of data/battery by NOT retrieving the same thing over and over. You can also avoid colliding with other clients, and instead, be alerted when you need to reconcile differences.

Hence, with just a little tweaking on your frontend and some entity-level edits, the backend will serve up time sensitive details you can cash in on when building a customer-friendly client.

If you would rather not use the bean name prefix approach, then you simply need to register an instance of your validator with the bean whose job it is to invoke validators after the correct event. In your configuration that implements RepositoryRestConfigurer or subclasses Spring Data REST’s RepositoryRestConfigurerAdapter, override the configureValidatingRepositoryEventListener method and call addValidator on the ValidatingRepositoryEventListener, passing the event you want this validator to be triggered on, and an instance of the validator.

There is an abstract class you can subclass which listens for these kinds of events and calls the appropriate method based on the event type. You just override the methods for the events you’re interested in.

One thing to note with this approach, however, is that it makes no distinction based on the type of the entity. You’ll have to inspect that yourself.

Another approach is to use an annotated handler, which does filter events based on domain type.

To declare a handler, create a POJO and put the @RepositoryEventHandler annotation on it. This tells the BeanPostProcessor that this class needs to be inspected for handler methods.

Once it finds a bean with this annotation, it iterates over the exposed methods and looks for annotations that correspond to the event you’re interested in. For example, to handle `BeforeSaveEvent`s in an annotated POJO for different kinds of domain types, you’d define your class like this:

The domain type whose events you’re interested in is determined from the type of the first parameter of the annotated methods.

To register your event handler, either mark the class with one of Spring’s @Component stereotypes so it can be picked up by @SpringBootApplication or @ComponentScan. Or declare an instance of your annotated bean in your ApplicationContext. Then the BeanPostProcessor that is created in RepositoryRestMvcConfiguration will inspect the bean for handlers and wire them to the correct events.

Sometimes you need to add links to exported resources in your own custom built Spring MVC controllers. There are three basic levels of linking available:

The first suggestion is terrible and should be avoided at all costs. It makes your code brittle and high risk. The second is handy when creating links to other hand written Spring MVC controllers. The last one, which you’ll see in a moment, is good for looking up resource links that are exported by Spring Data REST.

Assuming you have configured your code to use Spring’s autowiring,

…​you can then use the following operations:

Spring Data REST provides an ALPS document for every exported repository. It contains information about both the RESTful transitions as well as the attributes of each repository.

At the root of a Spring Data REST app is a profile link. Assuming you had an app with both persons and related addresses, the root document would look like this:

A profile link, as defined in RFC 6906, is a place to include application level details. The ALPS draft spec is meant to define a particular profile format which we’ll explore further down in this section.

If you navigate into the profile link at localhost:8080/profile, you would see something like this:

Let’s navigate to /profile/persons and look at the profile data for a Person resource.

You will also find a "profile" link shown in the collection of _links when you are looking at a collection resource.

The profile link, again, will serve up ALPS by default or if you use an Accept header of application/alps+json.

JSON Schema is another form of metadata supported by Spring Data REST. Per their website, JSON Schema has the following advantages:

As shown in the previous section, you can reach this data by navigating from the root URI to the "profile" link.

These links are the same as shown earlier. To retrieve JSON Schema you invoke them with Accept header application/schema+json.

In this case, if you executed curl -H 'Accept:application/schema+json' http://localhost:8080/profile/persons, you would see something like this:

There are more details if your resources have links to other resources.

You will also find a "profile" link shown in the collection of _links when you are looking at a collection resource.

The profile link, again, will serve up ALPS by default. If you supply it with an Accept header of application/schema+json, it will render the JSON Schema representation.

The following example from Spring Data REST’s test suite shows Spring Security’s PreAuthorization model, the most sophisticated version:

This is a standard Spring Data repository definition extending CrudRepository with some key changes.

The previous example illustrates that CrudRepository, in fact, has four delete methods. You must override all delete methods to properly secure it.

The following example shows Spring Security’s older @Secured annotation, which is purely role-based:

To configure method level security, here is a brief snippet from Spring Data REST’s test suite:

The rest of the configuration class isn’t listed because it follows standard practices you can read about in the Spring Security reference docs.

The developer of the HAL spec has a useful application: the HAL Browser. It’s a web app that stirs in a little HAL-powered JavaScript. You can point it at any Spring Data REST API and use it to navigate the app and create new resources.

Instead of pulling down the files, embedding them in your application, and crafting a Spring MVC controller to serve them up, all you need to do is add a single dependency.

In Maven:

In Gradle:

This dependency will autoconfigure the HAL Browser to be served up when you visit your application’s root URI in a browser. (NOTE: http://localhost:8080 was plugged into the browser, and it redirect to the URL shown below.)

The screen shot above shows the root path of the API. On the right side are details from the response including headers and the body (a HAL document).

The HAL Browser reads the links from the response and puts them on a list on the left side. You can either click on the GET button and navigate to one of the collections, or click on the non-GET option to make changes.

The HAL Browser speaks URI Template. You may notice up above the GET button next to persons has a question mark icon. An expansion dialog will pop-up if you choose to navigate to it like this:

If you click Follow URI without entering anything, the variables will essentially be ignored. For situations like Projections and Excerpts or Paging and Sorting, this can be useful.

When you click on a non-GET button, a pop-up dialog appears. By default, it shows POST. This field can be adjusted to either PUT or PATCH. The headers are filled out to properly to submit a new JSON document.

Below the URI, method, and headers are the fields. These are automatically supplied based on the metadata of the resources, automatically generated by Spring Data REST. Update your domain objects, and the pop-up will reflect it.

By default the URI for item resources are comprised of the path segment used for the collection resource with the database identifier appended. That allows us to use the repository’s findOne(…) method to lookup entity instances. As of Spring Data REST 2.5 this can be customized by using configuration API on RepositoryRestConfiguration (preferred on Java 8) or by registering an implementation of EntityLookup as Spring bean in your application. Spring Data REST will pick those up and tweak the URI generation according to their implementation.

Assume a User with a username property that uniquely identifies it. Also, assume we have a method Optional<User> findByUsername(String username) on the according repository.

On Java 8 we can simply register the mapping methods as method references to weak the URI creation as follows:

forRepository(…) takes the repository type as first argument a method reference mapping the repositories domain type to some target type, as well as another method reference to map that value back using the repository mentioned as first argument.

If you’re not running Java 8 or better, you could use the method but it would require a few quite verbose anonymous inner classes to be use. That’s why on older Java versions you probably prefer implementing a UserEntityLookup looking like this:

Note, how getResourceIdentifier(…) returns the username to be used by the URI creation. To load entity instances by the value returned from that method we now implement lookupEntity(…) using the query method available on the UserRepository.

Configuring the segments of the URL path under which the resources of a JPA repository are exported is simple. You just add an annotation at the class level and/or at the query method level.

By default, the exporter will expose your CrudRepository using the name of the domain class. Spring Data REST also applies the Evo Inflector to pluralize this word. So a repository defined as follows:

Will, by default, be exposed under the URL http://localhost:8080/persons/

To change how the repository is exported, add a @RestResource annotation at the class level:

Now the repository will be accessible under the URL: http://localhost:8080/people/

If you have query methods defined, those also default to be exposed by their name:

This would be exposed under the URL: http://localhost:8080/persons/search/findByName

To change the segment of the URL under which this query method is exposed, use the @RestResource annotation again:

Now this query method will be exposed under the URL: http://localhost:8080/people/search/names

If you have an existing Spring MVC application and you’d like to integrate Spring Data REST, it’s actually very easy.

Somewhere in your Spring MVC configuration (most likely where you configure your MVC resources) add a bean reference to the JavaConfig class that is responsible for configuring the RepositoryRestController. The class name is org.springframework.data.rest.webmvc.RepositoryRestMvcConfiguration.

In Java, this would look like:

In XML this would look like:

When your ApplicationContext comes across this bean definition it will bootstrap the necessary Spring MVC resources to fully-configure the controller for exporting the repositories it finds in that ApplicationContext and any parent contexts.

Sometimes you may want to write a custom handler for a specific resource. To take advantage of Spring Data REST’s settings, message converters, exception handling, and more, use the @RepositoryRestController annotation instead of a standard Spring MVC @Controller or @RestController:

This controller will be served from the same API base path defined in RepositoryRestConfiguration.setBasePath that is used by all other RESTful endpoints (e.g. /api). It also has these characteristics:

Resources is for a collection while Resource is for a single item. These types can be combined. If you know the links for each item in a collection, use Resources<Resource<String>> (or whatever the core domain type is). This lets you assemble links for each item as well as for the whole collection.

If you’re NOT interested in entity-specific operations but still want to build custom operations underneath basePath, such as Spring MVC views, resources, etc. use @BasePathAwareController.

Sometimes in your application you need to provide links to other resources from a particular entity. For example, a Customer response might be enriched with links to a current shopping cart, or links to manage resources related to that entity. Spring Data REST provides integration with Spring HATEOAS and provides an extension hook for users to alter the representation of resources going out to the client.

Sometimes the behavior of the Spring Data REST’s ObjectMapper, which has been specially configured to use intelligent serializers that can turn domain objects into links and back again, may not handle your domain model correctly. There are so many ways one can structure your data that you may find your own domain model isn’t being translated to JSON correctly. It’s also sometimes not practical in these cases to try and support a complex domain model in a generic way. Sometimes, depending on the complexity, it’s not even possible to offer a generic solution.

So to accommodate the largest percentage of the use cases, Spring Data REST tries very hard to render your object graph correctly. It will try and serialize unmanaged beans as normal POJOs and it will try and create links to managed beans where that’s necessary. But if your domain model doesn’t easily lend itself to reading or writing plain JSON, you may want to configure Jackson’s ObjectMapper with your own custom type mappings and (de)serializers.

For security reasons, browsers prohibit AJAX calls to resources residing outside the current origin. When working with client-side HTTP requests issued by a browser you want to enable specific HTTP resources to be accessible.

Spring Data REST supports as of 2.6 Cross-origin resource sharing (CORS) through Spring’s CORS support.

This example shows how to mix together several underlying Spring Data projects.

This example contains more detailed code you can use to poke around with projections.

This example shows how to secure a Spring Data REST application in multiple ways with Spring Security.

This example exposes 10843 Starbucks coffee shops via a RESTful API that allows to access the stores in a hypermedia based way and exposes a resource to execute geo-location search for coffee shops.