1. Introduction
Prev   Next

1. Introduction

Spring Data REST makes exporting domain objects to RESTful clients using HATEOAS principles very easy. It exposes the CRUD methods of the Spring Data CrudRepository interface to HTTP. Spring Data REST also reads the body of HTTP requests and interprets them as domain objects. It recognizes relationships between entities and represents that relationship in the form of aLink.

1.1 HTTP Verb to CRUD Method Mapping

Spring Data REST translates HTTP calls to method calls by mapping the HTTP verbs to CRUD methods. The following table illustrates the way in which an HTTP verb is mapped to a CrudRepository method.

Table 1.1. HTTP verb to CRUD method mapping
Verb Method
GET CrudRepository<ID,T>.findOne(ID id)
POST CrudRepository<ID,T>.save(T entity)
PUT CrudRepository<ID,T>.save(T entity)
DELETE CrudRepository<ID,T>.delete(ID id)

By default, all of these methods are exported to clients. By placing an annotation on your CrudRepository subinterface, however, you can turn access to a method off. This is discussed in more detail in the section on configuration.

1.2 Resource Discoverability

A core principle of HATEOAS is that resources should be discoverable through the publication of links that point to the available resources. There are a number of ways to accomplish this but no real standard way. Spring Data REST uses a link method that is consistent across Spring Data REST: it provides links in a property called links. That property is an array of objects that take the form of something resembling an atom:link element in the Atom XML namespace.

Resource discovery starts at the top level of the application. By issuing a request to the root URL under which the Spring Data REST application is deployed, the client can extract a set of links from the returned JSON object that represent the next level of resources that are available to the client.

For example, to discover what resources are available at the root of the application, issue an HTTP GET to the root URL: 

curl -v http://localhost:8080/

< HTTP/1.1 200 OK
< Content-Type: application/json
<
{
  "links" : [ {
    "rel" : "customer",
    "href" : "http://localhost:8080/customer"
  }, {
    "rel" : "profile",
    "href" : "http://localhost:8080/profile"
  }, {
    "rel" : "order",
    "href" : "http://localhost:8080/order"
  }, {
    "rel" : "people",
    "href" : "http://localhost:8080/people"
  }, {
    "rel" : "product",
    "href" : "http://localhost:8080/product"
  } ],
  "content" : [ ]
}

The links property of the result document contains an array of objects that have rel and href properties on them.

1.2.1 Compact vs. Verbose

When issuing a request to a resource, the default behavior is to provide as much information as possible in the body of the response. In the case of accessing a Repository resource, Spring Data REST will inline entities into the body of the response. This could lead to poor network performance in the case of a very large number of entities. To reduce the amount of data sent back in the response, a user agent can request the special content type application/x-spring-data-compact+json by placing this in the request Accept header. Rather than inlining the entities, this content-type provides a link to each entity in the links property. 

curl -v -H "Accept: application/x-spring-data-compact+json" http://localhost:8080/customer

< HTTP/1.1 200 OK
< Content-Type: application/x-spring-data-compact+json
<
{
  "links" : [ {
    "rel" : "customer.search",
    "href" : "http://localhost:8080/customer/search"
  } ],
  "content" : [ ]
}
Prev   Next
Spring Data REST Reference Documentation Home 2. Installing Spring Data REST