getting-started.adoc

Getting started

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.

Adding Spring Data REST to a Spring Boot project

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.

Spring Boot configuration with Gradle

dependencies {
  ...
  compile("org.springframework.boot:spring-boot-starter-data-rest")
  ...
}

Spring Boot configuration with Maven

<dependencies>
  ...
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-rest</artifactId>
  </dependency>
  ...
</dependencies>

Note	You don’t have to supply the version number if you are using the Spring Boot Gradle plugin or the Spring Boot Maven plugin.

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

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:{version}")
}

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>{version}</version>
</dependency>

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 and that class can just be imported into your applications configuration.

Important

This step is unnecessary if you are using Spring Boot’s auto-configuration. Spring Boot will automatically enable Spring Data REST when you include spring-boot-starter-data-rest and either in your list of dependencies, and you your app is flagged with either @SpringBootApplication or @EnableAutoConfiguration.

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.

Basic settings for Spring Data REST

Which repositories get exposed by defaults?

Spring Data REST uses a RepositoryDetectionStrategy to determine if a repository will be exported as REST resource or not. The following strategies (enumeration values of RepositoryDiscoveryStrategies) are available:

Table 1. Repository detection strategies

Name	Description
DEFAULT	Exposes all public repository interfaces but considers @(Repository)RestResource’s `exported flag.
ALL	Exposes all repositories independently of type visibility and annotations.
ANNOTATION	Only repositories annotated with @(Repository)RestResource are exposed, unless their exported flag is set to false.
VISIBILITY	Only public repositories annotated are exposed.

With Spring Boot 1.2+, strategy configurable via application.properties:

spring.data.rest.detection-strategy=annotated

Changing the base URI

By default, Spring Data REST serves up REST resources at the root URI, "/". There are multiple ways to change the base path.

With Spring Boot 1.2+, all it takes is a single property in application.properties:

spring.data.rest.basePath=/api

With Spring Boot 1.1 or earlier, or if you are not using Spring Boot, simply do this:

@Configuration
class CustomRestMvcConfiguration {

  @Bean
  public RepositoryRestConfigurer repositoryRestConfigurer() {

    return new RepositoryRestConfigurerAdapter() {

      @Override
      public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
        config.setBasePath("/api");
      }
    };
  }
}

Alternatively just register a custom implementation of RepositoryRestConfigurer as Spring bean and make sure it gets picked up by component scanning:

@Component
public class CustomizedRestMvcConfiguration extends RepositoryRestConfigurerAdapter {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
    config.setBasePath("/api");
  }
}

Both of these approaches will change the base path to /api.

Changing other Spring Data REST properties

There are many properties you can alter:

Table 2. Spring Boot configurable properties

Name	Description
basePath	root URI for Spring Data REST
defaultPageSize	change default number of items served in a single page
maxPageSize	change maximum number of items in a single page
pageParamName	change name of the query parameter for selecting pages
limitParamName	change name of the query parameter for number of items to show in a page
sortParamName	change name of the query parameter for sorting
defaultMediaType	change default media type to use when none is specified
returnBodyOnCreate	change if a body should be returned on creating a new entity
returnBodyOnUpdate	change if a body should be returned on updating an entity

Starting the application

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

Spring Data REST officially supports:

• Spring Data JPA

• Spring Data MongoDB

• Spring Data Neo4j

• Spring Data GemFire

• Spring Data Cassandra

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

• Spring Data JPA

• Spring Data MongoDB

• Spring Data Neo4j

• Spring Data GemFire

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.

Note	In general Spring Data REST doesn’t add functionality to a given data store. This means that by definition, it should work with any Spring Data project that supports the Repository programming model. The data stores listed above are simply the ones we have written integration tests to verify.

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