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.

To install Spring Data REST alongside your application, simply add the required dependencies, include the stock @Configuration class RepositoryRestMvcConfiguration (or subclass it and perform any required manual configuration), and map some URLs to be managed by Spring Data REST.

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

dependencies {
  … other project dependencies
  compile "org.springframework.data:spring-data-rest-webmvc:${spring-data-rest-version}"
}

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

<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-rest-webmvc</artifactId>
  <version>${spring-data-rest-version}</version>
</dependency>

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. You can either import this class into your existing configuration using an @Import annotation or you can subclass it and override any of the configureXXX methods to add your own configuration to that of Spring Data REST.

In the following example, we'll subclass the standard RepositoryRestMvcConfiguration and add some ResourceMapping configurations for the Person domain object to alter how the JSON will look and how the links to related entities will be handled.

@Configuration
@Import(RepositoryRestMvcConfiguration.class)
public class MyWebConfiguration extends RepositoryRestMvcConfiguration {

  // … further configuration
}

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.

As Spring Data REST is build on SpringMVC, you simply stick to the means you use to bootstrap Spring MVC. In a Servlet 3.0 environment this might look something like this:

public class RestExporterWebInitializer implements WebApplicationInitializer {

  @Override public void onStartup(ServletContext servletContext) throws ServletException {

    // Bootstrap repositories in root application context
    AnnotationConfigWebApplicationContext rootCtx = new AnnotationConfigWebApplicationContext();
    rootCtx.register(JpaRepositoryConfig.class); // Include JPA entities, Repositories
    servletContext.addListener(new ContextLoaderListener(rootCtx));

    // Enable Spring Data REST in the DispatcherServlet
    AnnotationConfigWebApplicationContext webCtx = new AnnotationConfigWebApplicationContext();
    webCtx.register(MyWebConfiguration.class);

    DispatcherServlet dispatcherServlet = new DispatcherServlet(webCtx);
    ServletRegistration.Dynamic reg = servletContext.addServlet("rest-exporter", dispatcherServlet);
    reg.setLoadOnStartup(1);
    reg.addMapping("/*");
  }
}

The equivalent of the above in a standard web.xml will also work identically to this configuration if you are still in a servlet 2.5 environment. When you deploy this application to your servlet container, you should be able to see what repositories are exported by accessing the root of the application.

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 a an item resource for each of the items managed by te 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.

curl -v http://localhost:8080/

< HTTP/1.1 200 OK
< Content-Type: application/hal+json

{ "_links" : {
    "orders" : {
      "href" : "http://localhost:8080/orders"
    }
  }
}

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.

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

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.

@Entity
public class MyEntity {
  @OneToMany
  private List<MyInterface> interfaces;
}

  @Override protected void configureJacksonObjectMapper(ObjectMapper objectMapper) {
    objectMapper.registerModule(new SimpleModule("MyCustomModule"){
      @Override public void setupModule(SetupContext context) {
        context.addAbstractTypeResolver(
          new SimpleAbstractTypeResolver().addMapping(MyInterface.class,
                                                      MyInterfaceImpl.class)
        );
      }
    });
  }

@Override public void setupModule(SetupContext context) {
  SimpleSerializers serializers = new SimpleSerializers();
  SimpleDeserializers deserializers = new SimpleDeserializers();

  serializers.addSerializer(MyEntity.class, new MyEntitySerializer());
  deserializers.addDeserializer(MyEntity.class, new MyEntityDeserializer());

  context.addSerializers(serializers);
  context.addDeserializers(deserializers);
}

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 who's job it is to invoke validators after the correct event. In your configuration that subclasses Spring Data REST's RepositoryRestMvcConfiguration, override the configureValidatingRepositoryEventListener method and call the addValidator method on the ValidatingRepositoryEventListener, passing the event you want this validator to be triggered on, and an instance of the validator.

@Override protected void configureValidatingRepositoryEventListener(ValidatingRepositoryEventListener v) {
  v.addValidator("beforeSave", new BeforeSaveValidator());
}

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.

public class BeforeSaveEventListener extends AbstractRepositoryEventListener {

  @Override public void onBeforeSave(Object entity) {
    ... logic to handle inspecting the entity before the Repository saves it
  }

  @Override public void onAfterDelete(Object entity) {
    ... send a message that this entity has been deleted
  }

}

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 BeforeSaveEvents in an annotated POJO for different kinds of domain types, you'd define your class like this:

@RepositoryEventHandler
public class PersonEventHandler {

  @HandleBeforeSave(Person.class) public void handlePersonSave(Person p) {
    ... you can now deal with Person in a type-safe way
  }

  @HandleBeforeSave(Profile.class) public void handleProfileSave(Profile p) {
    ... you can now deal with Profile in a type-safe way
  }

}

You can also declare the domain type at the class level:

@RepositoryEventHandler(Person.class)
public class PersonEventHandler {

  @HandleBeforeSave public void handleBeforeSave(Person p) {
    ...
  }

  @HandleAfterDelete public void handleAfterDelete(Person p) {
    ...
  }

}

Just declare an instance of your annotated bean in your ApplicationContext and the BeanPostProcessor that is by default created in RepositoryRestMvcConfiguration will inspect the bean for handlers and wire them to the correct events.

@Configuration
public class RepositoryConfiguration {

  @Bean PersonEventHandler personEventHandler() {
    return new PersonEventHandler();
  }

}