2. Getting started

2.1 Introduction

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.

2.2 Adding Spring Data REST to a Gradle project

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}"
}

2.3 Adding Spring Data REST to a Maven project

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>

2.4 Configuring Spring Data REST

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.

2.5 Starting the application

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.