Spring Data REST: your Spring Data repository as an HTTP API

The repository interface becomes the API surface

Spring Data REST exists to simplify building hypermedia-driven REST web services on top of Spring Data repositories. The README states the mechanism plainly: it takes your Spring Data repositories and fronts them with HTTP, giving you full CRUD over your entities, including managing associations.

That is the entire value proposition in one sentence. There is no controller to write and no service layer to thread through. A repository interface is enough, and the framework derives the routes, the representations and the content negotiation from it.

The declared feature set is what makes this more than a mapper. It exposes a discoverable REST API for your domain model using HAL as the media type. It exposes collection, item and association resources representing your model. Pagination is supported through navigational links. Collection resources can be filtered dynamically. Query methods defined in your repositories get their own search resources. You can hook into the handling of REST requests by handling Spring ApplicationEvents. Model metadata is exposed as ALPS and JSON Schema. Client specific representations can be defined through projections and excerpts. The latest release of HAL Explorer ships with the project so you can explore HAL and HAL-FORMS responses in a browser. And the default resources can be customised in advanced ways.

Store support is broad: JPA, MongoDB, Neo4j, Solr, Cassandra and Gemfire are listed. That list matters, because the point of the project is that the same API shape sits on top of very different persistence stacks.

Who this is for is a Spring team with an existing repository layer that needs an HTTP surface for a front end, a mobile client or another service, and who wants that surface to be self describing rather than hand rolled.

HAL, navigational links and ALPS describe the model to clients

The media type choice is HAL, and it is not cosmetic. The API is hypermedia-driven, which means responses carry links rather than just data, and a client can follow them to discover what it can do next.

Pagination rides on the same mechanism. Rather than returning a page of results with a count, the framework uses navigational links, so a client follows a link to the next page instead of constructing the offset itself. For a client written against this API, that is a meaningful difference from hand written paging, because the server decides what the next URL is.

The model is also exposed as machine readable metadata. ALPS describes the model as discovered, and JSON Schema is available as well. For a client team that wants to generate a client or drive a form, that metadata is the machine readable half of the story, and it is generated rather than maintained by hand.

The HAL Explorer that ships with the project is the counterpart for humans. It is there so you can open a URL and see what the API actually returns, which is a faster loop than writing a client before you know the shape of the response.

Dynamic filtering of collection resources rounds out the read side. The filters are applied to collection resources, so a client can narrow a listing without a dedicated endpoint per filter combination.

One point to hold onto while reading further: all of this is derived from your domain model. The metadata, the links and the resource names come from your entities, your repository interfaces and the annotations on them. That is the source of the speed and also the source of the constraint.

Declaring a repository is the whole setup

The getting started section shows a quick teaser of an application using Spring Data REST in Java, and it is short enough to read in full.

@CrossOrigin
@RepositoryRestResource(path = "people")
public interface PersonRepository extends CrudRepository<Person, Long> {

  List<Person> findByLastname(String lastname);

  @RestResource(path = "byFirstname")
  List<Person> findByFirstnameLike(String firstname);
}

Three things are doing the work here. The interface extends CrudRepository, which is what gives the generic CRUD endpoints. The @RepositoryRestResource annotation sets the base path, here people. The @RestResource annotation on a method overrides the path the framework would otherwise derive from the method name.

The persistence side is ordinary Spring configuration, and the example wires MongoDB.

@Configuration
@EnableMongoRepositories
class ApplicationConfig extends AbstractMongoConfiguration {

  @Override
  public MongoClient mongoClient() {
    return new MongoClient();
  }

  @Override
  protected String getDatabaseName() {
    return "springdata";
  }
}

The @EnableMongoRepositories annotation is the switch that turns the repositories into REST resources. Switch to another store, change the configuration and the API stays the same.

For Maven users the dependency is a single declaration.

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

If you want the latest snapshots of the upcoming major version, the README points at the Spring snapshot repository and the matching dependency version, with the repository declaration included so Maven can resolve it.

Nothing else is required. There is no controller, no serializer configuration and no message converter to wire.

Query methods become search resources you can call over HTTP

The second repository method in the example is where the framework earns its keep beyond plain CRUD. Spring Data already knows how to derive a query from a method name, and Spring Data REST exposes those queries as search resources.

In the example, findByFirstnameLike is annotated with @RestResource(path = "byFirstname"), which fixes the path segment instead of leaving it to be derived. The result is callable directly.

curl -v "http://localhost:8080/people/search/byFirstname?firstname=Oliver*&sort=name,desc"

The URL shows the conventions. Search resources live under a search path, the query parameter is named after the method argument, and the standard query string options such as sorting are available. The wildcard in the value is the Like suffix from the method name being carried through to the URL, so the client controls the pattern.

The other method in the example, findByLastname, carries no annotation, which means the path segment is derived from the method name. That is convenient when your method names read like your domain and awkward when they do not, and the annotation is the escape hatch for those cases.

This is the part of the design that determines whether the API suits your team. Method names become public URLs, and query method signatures become public query parameters. That is a strong coupling between internal naming and external contract, and it means renaming a repository method is a breaking change to any client that calls the search resource.

Projections, excerpts and advanced customisation of the default resources

A generic API has a generic shape, and Spring Data REST offers several ways to narrow that shape without giving up the generated endpoints.

Projections and excerpts let you define client specific representations. In a Spring Data context a projection selects a subset of an entity's properties, and an excerpt applies a projection to a particular method, so the same entity can be exposed in different shapes to different callers. For a front end that only needs four fields out of thirty, that is a way to keep the payload small without maintaining a second endpoint.

Beyond that, the README lists advanced customizations of the default resources exposed. The framework is not limited to a fixed set of routes: the default resources can be adjusted, which is what you reach for when the generated representation does not fit but you still want the rest of the generated endpoints.

The other extension point is events. You can hook into the handling of REST requests by handling Spring ApplicationEvents, so a listener can observe or react to what the framework is doing without replacing the generated handlers.

There is a deliberate limit to all of this. The project documentation describes the API in terms of your domain model and your repositories, and the customization story is about adjusting the resources it already exposes. If your API needs to be something other than a representation of the data model, with request payloads that carry business meaning, validation rules that span resources, or responses that are not entity shaped, you are fighting the framework rather than using it, and the alternative is to write the controllers yourself.

The alternative is hand written controllers over the same repositories

The realistic alternative to Spring Data REST is not another library but the traditional Spring MVC controller layer, and the difference in approach is worth spelling out.

A hand written controller sits between the client and the repository. You choose the URL, you choose the method signature, you decide what goes into the response, you add validation, you write the error handling, and you decide what happens with an association that the client sent. Nothing about your domain classes or your repository method names leaks into the public contract, because you wrote the contract.

Spring Data REST inverts that. The domain model is the contract. The entity names, the repository names, the associations between entities and the derived query method names all become visible to clients. You get consistency across every repository for free, and you get ALPS and JSON Schema metadata that you would otherwise have to maintain by hand or with a separate specification.

The two approaches also fail differently. Hand written controllers are more code and more places for inconsistency, but every unusual case is expressible. Spring Data REST is less code and uniform, but the URL space and the shape of the responses are consequences of your model rather than decisions you make. If your domain model is a poor fit for the API you want to publish, that uniformity becomes a liability.

There is a third path worth naming: write plain Spring MVC controllers but keep using Spring Data repositories underneath. That gives you the API control without giving up the repository layer, and it is the option to weigh when the API is a product rather than an internal convenience.

Apache 2.0, a five module layout and a 5.x release line

The licence is Apache 2.0, with the text in LICENSE.txt at the root of the repository. For a Spring project embedded in a commercial application, that is one of the more permissive and widely understood grants available, and it does not impose the copyleft obligations that a library under a reciprocal licence would.

The repository is split into modules that mirror the structure of the project: spring-data-rest-core holds the framework itself, spring-data-rest-webmvc is the web layer integration, spring-data-rest-hal-explorer is the bundled explorer, spring-data-rest-tests holds the test support, and spring-data-rest-distribution assembles the artefacts. There is also a src/ directory and a top level pom.xml.

Building it needs JDK 17 and either the bundled Maven wrapper or Maven 3.5.0 or above. The wrapper is the path the README recommends.

$ ./mvnw clean install

Building the reference documentation builds the project without running the tests, and the result lands in target/site/reference/html/index.html.

$ ./mvnw clean install -Pantora

Contributors are asked to sign the Spring Contributor Agreement before a first non-trivial change, and the README points at CONTRIBUTING.adoc for the details.

On maintenance, the repository is not archived and the last push was on 2026-10-14. The release line is active and in the middle of a minor cycle: 5.2.0-M2 on 2026-09-24, 5.2.0-M1 on 2026-08-21 and the maintenance release 5.1.1 on the same day. A project tracking the 5.x line should read the changelog, which the README links for new and noteworthy features, before upgrading across a minor version.

Editorial conclusion

Spring Data REST fits teams that already keep their data access in Spring Data repositories and want a usable CRUD and query API over that model without writing controllers. It does not fit projects whose API contract is not CRUD, whose resource shape must differ from the domain model, or who need authentication and authorisation rules, since the project documentation does not cover those. Verify first that the entity and repository names produce the URL paths and search resource names your consumers expect, then check that exposing associations in both directions does not leak more than you intend.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spring-projects/spring-data-rest on GitHub