The simplest way to get to started is to build a Spring Boot application because Spring Boot has a starter for Spring Data REST and uses auto-configuration. The following example shows how to use Gradle to include Spring Data Rest in a Spring Boot project:

The following example shows how to use Maven to include Spring Data Rest in a Spring Boot project:

When you use 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, as follows:

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

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 you can import that class into your application’s configuration.

To customize the configuration, register a RepositoryRestConfigurer 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, see the reference documentation for the corresponding Spring Data module.

This section covers the basic settings that you can manipulate when you configure a Spring Data REST application, including:

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

Spring Data REST officially supports:

The following Getting Started guides can 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 the links shown earlier) or configure it as a classic Spring MVC app.

From this point, you can 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 customize the way the exporting works is the repository interface. Consider 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 by using @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 resource defaults to the name of the association property and can be customized by 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 runs the exposed query 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 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:

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

The Spring Data REST exporter recognizes the returned Page 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.

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:

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.

To accommodate the largest percentage of use cases, Spring Data REST tries very hard to render your object graph correctly. It tries to serialize unmanaged beans as normal POJOs, and it tries to create links to managed beans where necessary. However, if your domain model does not easily lend itself to reading or writing plain JSON, you may want to configure Jackson’s ObjectMapper with your own custom mappings, serializers, and deserializers.

Consider the following domain model:

The Person object in the preceding example has several attributes:

Now assume that we create a corresponding repository, as follows:

By default, Spring Data REST exports this domain object, including all of its attributes. firstName and lastName are 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, as follows:

In this situation, a Person resource renders the address attribute as a URI to its 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 way. If the Address domain object does not have its own repository definition, Spring Data REST includes the data fields inside the Person resource, as the following example shows:

But what if you do not want address details at all? Again, by default, Spring Data REST exports all of its attributes (except the id). You can offer the consumer of your REST service an alternative by defining one or more projections. The following example shows a projection that does not include the address:

The NoAddresses projection only has getters for firstName and lastName, meaning that it does not serve up any address information. Assuming you have a separate repository for Address resources, the default view from Spring Data REST differs slightly from the previous representation, as the following example shows:

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

You can have multiple projections.

Spring Data REST finds projection definitions as follows:

In either case, the projection interface must have the @Projection annotation.

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

The preceding example 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 in the next section.

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.

Consider the following example:

The POJO in the preceding example, when served up as a REST resource by Spring Data REST, has 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 such as the following:

Only if the resource’s current ETag state matches the If-Match header is the operation carried out. This safeguard 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 gets 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 fails because they no longer match. Instead, that client receives 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 allows conditional queries. Consider the following example:

The preceding command (by default) runs a GET. Spring Data REST checks for If-None-Match headers while doing a GET. If the header matches the ETag, it concludes that nothing has changed and, instead of sending a copy of the resource, sends back an HTTP 304 Not Modified status code. Semantically, it reads “If this supplied header value does not match the server-side version, send the whole resource. Otherwise, do not send anything.”

The If-Modified-Since header provides a way to check whether a resource has been updated since the last request, which lets applications avoid resending the same data. Consider the following example:

With the date field in the preceding example, Spring Data REST returns a Last-Modified header similar to the following:

This value can be captured and used for subsequent queries to avoid fetching the same data twice when it has not been updated, as the following example shows:

With the preceding command, you are asking that a resource be fetched only if it has changed since the specified time. If so, you get a revised Last-Modified header with which to update the client. If not, you receive an HTTP 304 Not Modified status code.

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

ETag elements, combined with the If-Match and If-None-Match headers, let you build a front end that is more friendly to consumers' data plans and mobile battery lives. To do so:

By embedding ETag elements and Last-Modified values in your DOM (or perhaps elsewhere for a native mobile app), you can then reduce the consumption of data and battery power 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.

In this fashion, with just a little tweaking on your front end and some entity-level edits, the backend serves 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, you 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, override the configureValidatingRepositoryEventListener method and call addValidator on the ValidatingRepositoryEventListener, passing the event on which you want this validator to be triggered and an instance of the validator. The following example shows how to do so:

You can subclass an abstract class that listens for these kinds of events and calls the appropriate method based on the event type. To do so, override the methods for the events in question, as follows:

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

Another approach is to use an annotated handler, which filters 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 the BeanPostProcessor finds a bean with this annotation, it iterates over the exposed methods and looks for annotations that correspond to the event in question. For example, to handle BeforeSaveEvent instances in an annotated POJO for different kinds of domain types, you could define your class as follows:

The domain type whose events you are 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 that 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 inspects the bean for handlers and wires them to the correct events. The following example shows how to create an event handler for the Person class:

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 we explore in the rest of this section, is good for looking up resource links that are exported by Spring Data REST.

Consider the following class ,which uses Spring’s autowiring:

With the class in the preceding example, you can use the following operations:

Spring Data REST provides an ALPS document for every exported repository. It contains information about both the RESTful transitions and 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 be as follows:

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 explore later in this section.

If you navigate into the profile link at localhost:8080/profile, you see content resembling the following:

If you navigate to /profile/persons and look at the profile data for a Person resource, you see content resembling the following example:

You can also find a profile link in the collection of _links when you examine a collection resource, as the following example shows:

Again, by default, the profile link serves up ALPS. However, if you use an Accept header, it can serve 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 can invoke them with the following Accept header: application/schema+json.

In this case, if you ran curl -H 'Accept:application/schema+json' http://localhost:8080/profile/persons, you would see output resembling the following:

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

You can also find a profile link in the collection of _links when you examine a collection resource, as the following example shows:

Again, the profile link serves ALPS by default. If you supply it with an Accept header of application/schema+json, it renders the JSON Schema representation.

The following example from Spring Data REST’s test suite shows Spring Security’s PreAuthorization model (the most sophisticated security model):

The preceding example shows a standard Spring Data repository definition extending CrudRepository with some key changes: the specification of particular roles to access the various methods:

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 is not listed, because it follows standard practices that you can read about in the Spring Security reference docs.

Kai Tödter has created a useful application: HAL Explorer (Git Repo, Reference Doc, Demo). It is an Angular based web application that lets you easily explore HAL and HAL-FORMS based HTTP responses. It also supports Spring profiles generated by Spring Data REST. 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.

The following listing shows how to add the dependency in Maven:

The following listing shows how to add the dependency in Gradle:

This dependency auto-configures the HAL Explorer to be served up when you visit your application’s root URI in a browser. (NOTE: http://localhost:8080/api was plugged into the browser, and it redirected to the URL shown in the following image.)

The preceding screenshot 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 Explorer reads the links from the response and puts them in a list on the left side. You can either click on the green GET button and navigate to one of the collections, or click on the other buttons to make changes (POST, PUT, PATCH) or delete resources.

The HAL Explorer understands URI Templates. Whenever a link contains a URI template, a modal dialog pops up where you can enter the template parameters.

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

When you click on a NON-GET button with a + or a > sign on it, a modal dialog appears. It shows the HTTP method belonging to the clicked button. You can fill the body and submit the new JSON document.

Below the URI and HTTP method are the fields. These are automatically supplied, depending on the metadata of the resources, which was automatically generated by Spring Data REST. If you update your domain objects, the pop-up reflects it, as the following image shows:

By default, the URI for item resources are comprised of the path segment used for the collection resource with the database identifier appended. That lets you 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 a Spring bean in your application. Spring Data REST picks those up and tweaks the URI generation according to their implementation.

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

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

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

If you are not running Java 8 or better, you could use the method, but it would require a few quite verbose anonymous inner classes. On older Java versions, you should probably prefer implementing a UserEntityLookup that resembles the following:

Notice 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(…) by using the query method available on the UserRepository.

By default, all public Spring Data repositories are used to expose HTTP resources as described in Repository resources. Package protected repository interfaces are excluded from this list, as you express its functionality is only visible to the package internally. This can be customized by explicitly setting a RepositoryDetectionStrategy (usually through the enum RepositoryDetectionStrategies) on RepositoryRestConfiguration. The following values can be configured:

If you need custom rules to apply, simply implement RepositoryDetectionStrategy manually.

You can configure the segments of the URL path under which the resources of a JPA repository are exported. To do so, add an annotation at the class level or at the query method level.

By default, the exporter exposes your CrudRepository by using the name of the domain class. Spring Data REST also applies the Evo Inflector to pluralize this word. Consider the following repository definition:

The repository defined by the preceding example is exposed at http://localhost:8080/persons/.

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

The repository defined by the preceding example is accessible at http://localhost:8080/people/.

If you have query methods defined, those also default to being exposed by their name, as the following example shows:

The method in the preceding example is exposed at http://localhost:8080/persons/search/findByName.

To change the segment of the URL under which this query method is exposed, you can use the @RestResource annotation again, as the following example shows:

Now the query method in the preceding example is exposed at http://localhost:8080/people/search/names.

You can integrate Spring Data REST with an existing Spring MVC application. In your Spring MVC configuration (most likely where you configure your MVC resources), add a bean reference to the Java configuration class that is responsible for configuring the RepositoryRestController. The class name is org.springframework.data.rest.webmvc.RepositoryRestMvcConfiguration. The following example shows how to use an @Import annotation to add the proper reference:

In Java, this would look like:

The following example shows the corresponding XML configuration:

When your ApplicationContext comes across this bean definition, it bootstraps 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. Controllers annotated with @RepositoryRestController are served from the API base path defined in RepositoryRestConfiguration.setBasePath, which is used by all other RESTful endpoints (for example, /api). The following example shows how to use the @RepositoryRestController annotation:

CollectionModel is for a collection, while EntityModel — or the more general class RepresentationModel — is for a single item. These types can be combined. If you know the links for each item in a collection, use CollectionModel<EntityModel<String>> (or whatever the core domain type is rather than String). Doing so lets you assemble links for each item as well as for the whole collection.

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 that lets you alter the representation of resources that go out to the client.

Sometimes, the behavior of the Spring Data REST 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. You can structure your data in so many ways that you may find your own domain model does not correctly translate to JSON. It is also sometimes not practical in these cases to support a complex domain model in a generic way. Sometimes, depending on the complexity, it is not even possible to offer a generic solution.

To accommodate the largest percentage of the use cases, Spring Data REST tries to render your object graph correctly. It tries to serialize unmanaged beans as normal POJOs, and tries to create links to managed beans where necessary. However, if your domain model does not 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, as of 2.6, supports 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 explore projections.

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

This example exposes 10,843 Starbucks coffee shops through a RESTful API that allows access to the stores in a hypermedia-based way and exposes a resource to run a geo-location search for coffee shops.