[[install-chapter]]
= Getting started

[[getting-started.introduction]]
== 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.

[[getting-started.boot]]
== 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
[source,groovy]
----
dependencies {
  ...
  compile("org.springframework.boot:spring-boot-starter-data-rest")
  ...
}
----

.Spring Boot configuration with Maven
[source,xml]
----
<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 http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#build-tool-plugins-gradle-plugin[Spring Boot Gradle plugin] or the http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#build-tool-plugins-maven-plugin[Spring Boot Maven plugin].

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

[[getting-started.gradle]]
== 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:

[source,groovy,subs="verbatim,attributes"]
----
dependencies {
  … other project dependencies
  compile("org.springframework.data:spring-data-rest-webmvc:{version}")
}
----

[[getting-started.maven]]
== 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:

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.springframework.data</groupId>
  <artifactId>spring-data-rest-webmvc</artifactId>
  <version>{version}</version>
</dependency>
----

[[getting-started.configuration]]
== 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 http://projects.spring.io/spring-data/[corresponding Spring Data module].

[[getting-started.basic-settings]]
== 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:

.Repository detection strategies
[cols="1,5". options="header"]
|===
| 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.
|===

=== 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`:

[source,properties]
----
spring.data.rest.basePath=/api
----

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

[source,java]
----
@Configuration
class CustomRestMvcConfiguration {

  @Bean
  public RepositoryRestConfigurer repositoryRestConfigurer() {

    return new RepositoryRestConfigurerAdapter() {

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

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

[source,java]
----
@Component
public class CustomizedRestMvcConfiguration extends RepositoryRestConfigurerAdapter {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
    configuration.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:

.Spring Boot configurable properties
[cols="1,5". options="header"]
|===
| 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
|===

[[getting-started.bootstrap]]
== Starting the application

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

Spring Data REST officially supports:

* http://projects.spring.io/spring-data-jpa/[Spring Data JPA]
* http://projects.spring.io/spring-data-mongodb/[Spring Data MongoDB]
* http://projects.spring.io/spring-data-neo4j/[Spring Data Neo4j]
* http://projects.spring.io/spring-data-gemfire/[Spring Data GemFire]
* http://projects.spring.io/spring-data-cassandra/[Spring Data Cassandra]

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

* https://spring.io/guides/gs/accessing-data-rest/[Spring Data JPA]
* https://spring.io/guides/gs/accessing-mongodb-data-rest/[Spring Data MongoDB]
* https://spring.io/guides/gs/accessing-neo4j-data-rest/[Spring Data Neo4j]
* https://spring.io/guides/gs/accessing-gemfire-data-rest/[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 <<customizing-sdr,customize Spring Data REST>> with various options.