Spring Data REST

https://github.com/spring-projects/spring-data-rest
Admin
Spring Data REST simplifies building hypermedia-driven RESTful web services from Spring Data...
Tokens:28,974
Snippets:416
Trust Score:9.7
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build Spring Data REST with Maven Wrapper

Source: https://github.com/spring-projects/spring-data-rest/blob/main/README.adoc

Execute this command to clean and install the project using the Maven wrapper. Ensure you have JDK 17 installed.

```bash
 $ ./mvnw clean install

```

--------------------------------

### Discover Root Resources via HTTP GET

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Issue an HTTP GET request to the root URL to discover available resources. The response, in HAL format, contains links to top-level resources like 'orders' and 'profile'.

```http
curl -v http://localhost:8080/

< HTTP/1.1 200 OK
< Content-Type: application/hal+json

{
  "_links" : {
    "orders" : {
      "href" : "http://localhost:8080/orders"
    },
    "profile" : {
      "href" : "http://localhost:8080/api/alps"
    }
  }
}
```

--------------------------------

### Custom ALPS Descriptions using Properties

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/metadata.adoc

This example demonstrates how to define custom descriptions for resources and their fields in ALPS metadata by using a `rest-messages.properties` file.

```properties
rest.description.person=A collection of people
rest.description.person.id=primary key used internally to store a person (not for RESTful usage)
rest.description.person.firstName=Person's first name
rest.description.person.lastName=Person's last name
rest.description.person.address=Person's address
```

--------------------------------

### Search Resource - GET

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Returns links for all query methods exposed by a repository. Supports application/hal+json and application/json media types.

```APIDOC
## GET /api/search

### Description
Returns a list of links pointing to the individual query method resources.

### Method
GET

### Endpoint
/api/search

### Parameters
None

### Response
#### Success Response (200)
- Links to individual query method resources.

#### Supported Media Types
- application/hal+json
- application/json
```

--------------------------------

### Default Person Resource Representation (with Address Repository)

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

Example HAL document for a Person resource when an Address repository is defined. The address is represented as a link.

```javascript
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons/1"
    },
    "address" : {
      "href" : "http://localhost:8080/persons/1/address"
    }
  }
}
```

--------------------------------

### Enable JSONP with Default Callback Parameter

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

To enable JSONP, pass the `callback` URL parameter to your request. This example shows how to query for people by name.

```bash
curl -v http://localhost:8080/people/search/findByName?name=John+Doe&callback=my_json_callback
```

--------------------------------

### Conditional GET Request with If-None-Match

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc

Employ the If-None-Match header with GET requests to conditionally retrieve resources. If the header's ETag matches the server's current ETag, a 304 Not Modified status is returned, saving bandwidth.

```shell
curl -v -H 'If-None-Match: <value of previous etag>' ... 
```

--------------------------------

### JSONP Response Example

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

A typical JSONP response wraps the data in a JavaScript function call specified by the `callback` parameter.

```javascript
my_jsonp_callback({
			"results": [ ... ],
			"_links": [ ... ]
		})
```

--------------------------------

### Custom RepositoryRestController Example

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/overriding-sdr-response-handlers.adoc

Use @RepositoryRestController to create custom handlers for specific resources, leveraging Spring Data REST's features. This example shows how to define a custom GET endpoint that fetches data, performs post-processing, and returns a CollectionModel with self-links.

```java
@RepositoryRestController
class ScannerController {

  private final ScannerRepository repository;

  ScannerController(ScannerRepository repository) { // <1>
    this.repository = repository;
  }

  @GetMapping(path = "/scanners/search/producers") // <2>
  ResponseEntity<?> getProducers() {

    List<String> producers = repository.listProducers(); // <3>

    // do some intermediate processing, logging, etc. with the producers

    CollectionModel<String> resources = CollectionModel.of(producers); // <4>

    resources.add(linkTo(methodOn(ScannerController.class).getProducers()).withSelfRel()); // <5>

    // add other links as needed

    return ResponseEntity.ok(resources); // <6>
  }
}
```

--------------------------------

### Default Person Resource Representation (without Address Repository)

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

Example representation of a Person resource when no separate Address repository is defined. Address details are embedded.

```javascript
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "address" : {
    "street": "Bag End",
    "state": "The Shire",
    "country": "Middle Earth"
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons/1"
    }
  }
}
```

--------------------------------

### Default Query Method Exposure

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

Query methods are exposed under the 'search' resource by default, using their method name. This example shows a repository with a query method.

```java
interface PersonRepository extends CrudRepository<Person, Long> {

  List<Person> findByName(String name);
}
```

--------------------------------

### Association Resource Supported Methods

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Details the supported HTTP methods for association resources, including GET, PUT, POST, and DELETE.

```APIDOC
## GET /api/items/{id}/association

### Description
Retrieves the state of the association resource.

### Method
GET

### Endpoint
/api/items/{id}/association

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.
- **association** (string) - Required - The name of the association.

### Response
#### Success Response (200)
- **body** (object) - The state of the association resource.

## PUT /api/items/{id}/association

### Description
Replaces the state of the association resource.

### Method
PUT

### Endpoint
/api/items/{id}/association

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.
- **association** (string) - Required - The name of the association.

#### Request Body
- **field** (any) - Required - The new state of the association resource.

### Response
#### Success Response (200 or 204)
- **body** (object) - The updated association resource representation (if Accept header is present).
- **status** (integer) - 200 OK if a body is returned, 204 No Content if no body is returned.

## POST /api/items/{id}/association

### Description
Creates or updates an association.

### Method
POST

### Endpoint
/api/items/{id}/association

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.
- **association** (string) - Required - The name of the association.

#### Request Body
- **field** (any) - Required - The data for the association.

### Response
#### Success Response (200 or 201)
- **body** (object) - The created or updated association resource representation.
- **status** (integer) - 200 OK or 201 Created.

## DELETE /api/items/{id}/association

### Description
Deletes the association resource.

### Method
DELETE

### Endpoint
/api/items/{id}/association

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.
- **association** (string) - Required - The name of the association.

### Response
#### Success Response (200 or 204)
- **body** (object) - The deleted association resource representation (if Accept header is present).
- **status** (integer) - 200 OK if a body is returned, 204 No Content if no body is returned.
```

--------------------------------

### POST JSON to Create New Address

Source: https://github.com/spring-projects/spring-data-rest/wiki/Embedded-Entity-references-in-complex-object-graphs

Example cURL command to POST the JSON payload to create a new Address instance with a referenced Person.

```bash
curl -v -X POST -d '...json data...' http://localhost:8080/address
```

--------------------------------

### Fetch Person Links using Compact JSON

Source: https://github.com/spring-projects/spring-data-rest/wiki/Embedded-Entity-references-in-complex-object-graphs

Example cURL command to fetch a list of Person links using the compact JSON format. This is useful for obtaining entity references.

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

--------------------------------

### Person Resource JSON Schema

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/metadata.adoc

This is an example of the JSON Schema for the 'Person' resource. It details the properties, their types, and read-only status, useful for understanding the data structure and validation.

```json
{
  "title" : "org.springframework.data.rest.webmvc.jpa.Person",
  "properties" : {
    "firstName" : {
      "readOnly" : false,
      "type" : "string"
    },
    "lastName" : {
      "readOnly" : false,
      "type" : "string"
    },
    "siblings" : {
      "readOnly" : false,
      "type" : "string",
      "format" : "uri"
    },
    "created" : {
      "readOnly" : false,
      "type" : "string",
      "format" : "date-time"
    },
    "father" : {
      "readOnly" : false,
      "type" : "string",
      "format" : "uri"
    },
    "weight" : {
      "readOnly" : false,
      "type" : "integer"
    },
    "height" : {
      "readOnly" : false,
      "type" : "integer"
    }
  },
  "descriptors" : { },
  "type" : "object",
  "$schema" : "https://json-schema.org/draft-04/schema#"
}
```

--------------------------------

### Repository Link Rel Example Output

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

This JSON snippet illustrates the effect of customizing the repository's 'rel' attribute, changing the top-level link name from the default to 'people'.

```javascript
{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people"
    },
    …
  }
}
```

--------------------------------

### Default Query Method Exposure

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

Query methods are exposed under the 'search' resource by default, using their method name. For example, findByName is exposed under /person/search/findByName.

```java
public interface PersonRepository extends CrudRepository<Person, Long> {

  public List<Person> findByName(String name);

}
```

--------------------------------

### Example Domain Class with Interface Field

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/representations.adoc

A sample domain entity class that includes a field of an interface type. This demonstrates a scenario where custom Jackson configuration might be needed for abstract type resolution.

```java
@Entity
public class MyEntity {
  @OneToMany
  private List<MyInterface> interfaces;
}
```

--------------------------------

### Compact JSON Response with Person Links

Source: https://github.com/spring-projects/spring-data-rest/wiki/Embedded-Entity-references-in-complex-object-graphs

Example compact JSON response containing links to Person entities. These links are used to reference existing Person objects.

```json
{
	"links" : [ { "rel" : "people.Person", "href" : "http://localhost:8080/people/2" }, { "rel" : "people.Person", "href" : "http://localhost:8080/people/1" }, { "rel" : "people.search", "href" : "http://localhost:8080/people/search" } ],
	"content" : [ ],
	"page" : {
		"number" : 1,
		"size" : 20,
		"totalPages" : 1,
		"totalElements" : 2
	}
}
```

--------------------------------

### Query Method Resource - GET

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Runs an exposed query through an individual query method on the repository interface. Supports pagination parameters. Supports application/hal+json and application/json media types.

```APIDOC
## GET /api/query/{methodName}

### Description
Returns the result of the query executed by the specified query method.

### Method
GET

### Endpoint
/api/query/{methodName}

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to access (0 indexed, defaults to 0).
- **size** (integer) - Optional - The page size requested (defaults to 20).
- **sort** (string) - Optional - A collection of sort directives in the format `($propertyname,)+[asc|desc]?`.

### Response
#### Success Response (200)
- The result of the query.

#### Supported Media Types
- application/hal+json
- application/json
```

--------------------------------

### Default Query Method Link Rel

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

In HAL format, query methods are exposed with a 'rel' attribute matching their method name. This example shows the default JSON output for a query method link.

```javascript
{
  "_links" : {
    "findByName" : {
      "href" : "http://localhost:8080/persons/search/findByName"
    }
  }
}
```

--------------------------------

### JSON Payload for Creating an Address with Person Reference

Source: https://github.com/spring-projects/spring-data-rest/wiki/Embedded-Entity-references-in-complex-object-graphs

Example JSON payload for creating a new Address. It includes a direct link to an existing Person entity to satisfy the `optional = false` constraint.

```json
{
	"postalCode": "12345",
	"province": "MO",
	"lines": ["1 W 1st St."],
	"city": "Univille",
	"person": "http://localhost:8080/people/1"
}
```

--------------------------------

### Person Resource Representation with NoAddresses Projection

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

Example HAL document for a Person resource using the 'noAddresses' projection. Address information is omitted, and the self link is templated.

```javascript
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons/1{?projection}",
      "templated" : true
    },
    "address" : {
      "href" : "http://localhost:8080/persons/1/address"
    }
  }
}
```

--------------------------------

### Custom JSONP Callback Parameter Usage

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

After configuring a custom `jsonpParamName`, use that parameter in your request URL. This example uses the configured "jsonp" parameter.

```bash
curl -v http://localhost:8080/people/search/findByName?name=John+Doe&jsonp=my_json_callback
```

--------------------------------

### Person Entity Definition

Source: https://github.com/spring-projects/spring-data-rest/wiki/Embedded-Entity-references-in-complex-object-graphs

Defines a Person entity. This is a basic entity definition used in examples.

```java
@Entity
public class Person {
	// ... person's properties
}
```

--------------------------------

### Customizing Repository Path

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

Use the @RestResource annotation at the class level to change the path under which a Repository is exposed. This example changes the path to 'people'.

```java
@RestResource(path = "people")
public interface PersonRepository extends CrudRepository<Person, Long> {}
```

--------------------------------

### Default Repository Exposure

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

By default, a CrudRepository is exposed using its class name stripped of 'Repository'. For example, PersonRepository is exposed under /person/.

```java
public interface PersonRepository extends CrudRepository<Person, Long> {}
```

--------------------------------

### HAL Document with Inline Address Data

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

Example of a HAL document where the 'address' data is included inline due to the configured excerpt projection. The link to the address resource is still provided.

```javascript
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "address" : {
    "street": "Bag End",
    "state": "The Shire",
    "country": "Middle Earth"
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons/1"
    },
    "address" : {
      "href" : "http://localhost:8080/persons/1/address"
    }
  }
}
```

--------------------------------

### Define Domain with Interface Field

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/custom-jackson-deserialization.adoc

Example of a domain entity that uses an interface for a collection field. Jackson requires explicit configuration to instantiate implementations for interfaces.

```java
@Entity
public class MyEntity {

  @OneToMany
  private List<MyInterface> interfaces;
}
```

--------------------------------

### Customize Item Resource URIs with EntityLookupSupport (Older Java)

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing-sdr.adoc

Implement EntityLookupSupport to customize item resource URIs when not using Java 8+. This involves defining how to get the resource identifier and how to look up entities.

```java
@Component
public class UserEntityLookup extends EntityLookupSupport<User> {

    private final UserRepository repository;

    public UserEntityLookup(UserRepository repository) {
        this.repository = repository;
    }

    @Override
    public Serializable getResourceIdentifier(User entity) {
        return entity.getUsername();
    }

    @Override
    public Object lookupEntity(Serializable id) {
        return repository.findByUsername(id.toString());
    }
}
```

--------------------------------

### JSONP Error Response Example

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

When JSONP error handling is enabled, errors are returned as a JavaScript function call with the HTTP status code and error message.

```javascript
my_jsonp_error_handler(400, {
			"message": "Validation failed on property 'name'!",
			"cause": { ... }
		})
```

--------------------------------

### Query Family Members using curl

Source: https://github.com/spring-projects/spring-data-rest/wiki/Example-API-usage-with-curl

Use a GET request to retrieve the members of a family. The response is in JSON format and includes a list of associated people with their links.

```bash
$ curl -v http://localhost:8080/family/1/members
```

```json
{
  "links" : [ ],
  "content" : [ {
    "links" : [ {
      "rel" : "family.Family.members.Person",
      "href" : "http://localhost:8080/family/1/members/1"
    }, {
      "rel" : "peeps.Person.addresses",
      "href" : "http://localhost:8080/people/1/addresses"
    }, {
      "rel" : "peeps.Person.profiles",
      "href" : "http://localhost:8080/people/1/profiles"
    }, {
      "rel" : "self",
      "href" : "http://localhost:8080/people/1"
    } ],
    "name" : "John Doe"
  }, {
    "links" : [ {
      "rel" : "peeps.Person.addresses",
      "href" : "http://localhost:8080/people/2/addresses"
    }, {
      "rel" : "family.Family.members.Person",
      "href" : "http://localhost:8080/family/1/members/2"
    }, {
      "rel" : "peeps.Person.profiles",
      "href" : "http://localhost:8080/people/2/profiles"
    }, {
      "rel" : "self",
      "href" : "http://localhost:8080/people/2"
    } ],
    "name" : "Jane Doe"
  } ]
}
```

--------------------------------

### Enable JSONP Error Handling

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

To handle server errors with JSONP, set the `jsonpOnErrParamName` property in `RepositoryRestConfiguration`. This example shows how to trigger error handling with an "errback" parameter.

```bash
curl -v -d '...bad json data...' http://localhost:8080/people?errback=my_jsonp_error_handler
```

--------------------------------

### Sort Results by Name Descending

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

Use the `sort` URL parameter to order results by a specific property. Append `,desc` for descending order. This example sorts people by name.

```http
curl -v "http://localhost:8080/people/search/nameStartsWith?name=K&sort=name,desc"
```

--------------------------------

### Customizing Query Method Path

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

Use the @RestResource annotation on a query method to change its exposed path. This example changes the query method path to 'names'.

```java
@RestResource(path = "people")
public interface PersonRepository extends CrudRepository<Person, Long> {

  @RestResource(path = "names")
  public List<Person> findByName(String name);

}
```

--------------------------------

### Configure JSONP Callback Parameter Name

Source: https://github.com/spring-projects/spring-data-rest/wiki/JSONP-Support-in-Spring-Data-REST

Customize the URL parameter name for JSONP callbacks by setting the `jsonpParamName` property in `RepositoryRestConfiguration`. This JavaConfig example sets it to "jsonp".

```java
@Bean public RepositoryRestConfiguration restConfig() {
			return new RepositoryRestConfiguration().
				setJsonpParamName("jsonp");
		}
```

--------------------------------

### Query Spring Data REST API using curl

Source: https://github.com/spring-projects/spring-data-rest/blob/main/README.adoc

Example of how to query a custom search resource ('byFirstname') exposed by Spring Data REST using curl. Demonstrates filtering by firstname and sorting.

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

--------------------------------

### Default Repository Exposure

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

By default, Spring Data REST exposes repositories using the pluralized name of the domain class. This example shows a basic repository definition.

```java
interface PersonRepository extends CrudRepository<Person, Long> {}
```

--------------------------------

### Customizing Repository Path with @RepositoryRestResource

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

Use the @RepositoryRestResource annotation at the class level to change the base path for a repository. The example sets the path to "people".

```java
@RepositoryRestResource(path = "people")
interface PersonRepository extends CrudRepository<Person, Long> {}
```

--------------------------------

### Sort Results by Property with Direction

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

To sort results by a specific property, use the 'sort' URL parameter. Append ',asc' or ',desc' to specify the sort direction. This example sorts by 'name' in descending order.

```curl
curl -v http://localhost:8080/people/search/nameStartsWith?name=K&sort=name,desc
```

--------------------------------

### Paged Response Link Example

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

A paged response includes links to navigate between pages. The 'rel' value indicates whether it's a 'next' or 'prev' link, and 'href' provides the URL for that page.

```json
{
  "rel" : "people.next",
  "href" : "http://localhost:8080/people?page=2&limit=20"
}
```

--------------------------------

### Customizing Repository and Query Method Rels

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

Both the repository and its query methods can have their 'rel' attributes customized using the @RestResource annotation. This example sets the repository rel to 'people' and the query method rel to 'names'.

```java
@RestResource(path = "people", rel = "people")
public interface PersonRepository extends CrudRepository<Person, Long> {

  @RestResource(path = "names", rel = "names")
  public List<Person> findByName(String name);

}
```

--------------------------------

### Build Reference Documentation with Maven Wrapper

Source: https://github.com/spring-projects/spring-data-rest/blob/main/README.adoc

Use this command to build the project and its reference documentation without running tests. The documentation will be generated in `target/site/reference/html/index.html`.

```bash
 $ ./mvnw clean install -Pantora

```

--------------------------------

### Customizing Query Method Link Rel

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

Use the 'rel' property within the @RestResource annotation to customize the 'rel' attribute for a query method's link. This example sets the rel to "names".

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

  @RestResource(path = "names", rel = "names")
  List<Person> findByName(String name);
}
```

--------------------------------

### Fetch First Page with Page Size 5

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

This `curl` command fetches the first page of results with a page size of 5. Note the use of quotes around the URL when using `&`.

```bash
curl localhost:8080/people?size=5
```

--------------------------------

### Implement Person ResourceProcessor

Source: https://github.com/spring-projects/spring-data-rest/wiki/Customizing-the-JSON-output

Use this to add custom links to a Person resource. Ensure you have Spring HATEOAS configured.

```java
@Bean public ResourceProcessor<Resource<Person>> personProcessor() {
			return new ResourceProcessor<Resource<Person>>() {
				@Override public Resource<Person> process(Resource<Person> resource) {
					resource.add(new Link("http://localhost:8080/people", "added-link"));
					return resource;
				}
			};
		}
```

--------------------------------

### HAL Response for First Page

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

The HAL response for the first page includes `_links` for `self` and `next`, and a `page` object detailing pagination information like size, total elements, total pages, and current number.

```json
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons{&sort,page,size}",
      "templated" : true
    },
    "next" : {
      "href" : "http://localhost:8080/persons?page=1&size=5{&sort}",
      "templated" : true
    }
  },
  "_embedded" : {
  	… data …
  },
  "page" : {
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 0
  }
}
```

--------------------------------

### Link to All Search Resources

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/integration.adoc

Retrieves a list of links for all finder methods exposed by the repository corresponding to the specified entity type. Supports additional parameters for paging and sorting.

```java
entityLinks.linksToSearchResources(Person.class)
```

--------------------------------

### Set Page Size with 'limit' Parameter

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

When accessing a list of all entities from a repository that extends PagingAndSortingRepository, a 'limit' parameter can be added to the URL to specify the page size.

```http
http://localhost:8080/people/?limit=50
```

--------------------------------

### Fetch Second Page with Page Size 5

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

This `curl` command fetches the second page (page number 1) of results with a page size of 5. The response includes `prev` and `next` links.

```bash
$ curl "http://localhost:8080/persons?page=1&size=5"
```

--------------------------------

### Extend PagingAndSortingRepository for Paging Support

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

To enable paging for your repositories, extend the PagingAndSortingRepository interface. This interface provides methods that accept a Pageable object to manage the number and page of results.

```java
public Page findAll(Pageable pageable);
```

--------------------------------

### Item Resource Supported Methods

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Details the supported HTTP methods for item resources, including HEAD, PUT, PATCH, and DELETE.

```APIDOC
## HEAD /api/items/{id}

### Description
Checks for the availability of an item resource.

### Method
HEAD

### Endpoint
/api/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.

### Response
#### Success Response (200)
No specific body content is defined for HEAD requests.

## PUT /api/items/{id}

### Description
Replaces the state of the target resource with the supplied request body.

### Method
PUT

### Endpoint
/api/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.

#### Request Body
- **field** (any) - Required - The new state of the resource.

### Response
#### Success Response (200 or 204)
- **body** (object) - The updated resource representation (if Accept header is present).
- **status** (integer) - 200 OK if a body is returned, 204 No Content if no body is returned.

#### Error Response
- **405 Method Not Allowed**: If the save method is not exported or present.

## PATCH /api/items/{id}

### Description
Partially updates the resource's state.

### Method
PATCH

### Endpoint
/api/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.

#### Request Body
- **field** (any) - Required - The partial state of the resource to update.

### Response
#### Success Response (200 or 204)
- **body** (object) - The updated resource representation (if Accept header is present).
- **status** (integer) - 200 OK if a body is returned, 204 No Content if no body is returned.

#### Error Response
- **405 Method Not Allowed**: If the save method is not exported or present.

## DELETE /api/items/{id}

### Description
Deletes the exposed resource.

### Method
DELETE

### Endpoint
/api/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item.

### Response
#### Success Response (200 or 204)
- **body** (object) - The deleted resource representation (if Accept header is present).
- **status** (integer) - 200 OK if a body is returned, 204 No Content if no body is returned.

#### Error Response
- **405 Method Not Allowed**: If the delete method is not exported or present.
```

--------------------------------

### Query Method Resource - HEAD

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Returns whether a query method resource is available.

```APIDOC
## HEAD /api/query/{methodName}

### Description
Returns whether a query method resource is available.

### Method
HEAD

### Endpoint
/api/query/{methodName}

### Response
#### Success Response (200)
- Indicates the query method resource is available.
```

--------------------------------

### Customizing Repository Link Rel

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

The 'rel' property on the @RepositoryRestResource annotation can be used to customize the top-level link name for the repository. This example sets the rel to "people".

```java
@RepositoryRestResource(path = "people", rel = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

  @RestResource(path = "names", rel = "names")
  List<Person> findByName(String name);
}
```

--------------------------------

### Customizing Rel Attribute for Query Method

Source: https://github.com/spring-projects/spring-data-rest/wiki/Configuring-the-REST-URL-path

Use the 'rel' property on the @RestResource annotation to change the 'rel' attribute in links. This example sets the rel to 'names' for the findByName method.

```java
@RestResource(path = "people")
public interface PersonRepository extends CrudRepository<Person, Long> {

  @RestResource(path = "names", rel = "names")
  public List<Person> findByName(String name);

}
```

--------------------------------

### Global CORS Configuration with RepositoryRestConfigurer

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-cors.adoc

Define global CORS configuration by implementing `RepositoryRestConfigurer` and overriding the `configureRepositoryRestConfiguration` method. This allows for centralized configuration of CORS mappings, origins, methods, headers, and max age.

```java
@Component
public class SpringDataRestCustomization implements RepositoryRestConfigurer {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config, CorsRegistry cors) {

    cors.addMapping("/person/**")
      .allowedOrigins("http://domain2.example")
      .allowedMethods("PUT", "DELETE")
      .allowedHeaders("header1", "header2", "header3")
      .exposedHeaders("header1", "header2")
      .allowCredentials(false).maxAge(3600);
  }
}
```

--------------------------------

### Set Page Size with URL Parameter

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

To change the default page size (20 entities) when accessing a collection, append the 'size' parameter to the URL.

```http
http://localhost:8080/people/?size=5
```

--------------------------------

### Add a Family using curl

Source: https://github.com/spring-projects/spring-data-rest/wiki/Example-API-usage-with-curl

Use a POST request with JSON data to create a new 'Family' entity. The response includes a 'Location' header with the URL of the newly created resource.

```bash
$ curl -X POST -v -d '{"surname" : "Doe"}' -H "Content-Type: application/json" http://localhost:8080/family
```

--------------------------------

### HAL Response for Second Page

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/paging-and-sorting.adoc

The HAL response for the second page shows the current page number as 1 and includes both `prev` and `next` links for navigation.

```json
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons{&sort,projection,page,size}",
      "templated" : true
    },
    "next" : {
      "href" : "http://localhost:8080/persons?page=2&size=5{&sort,projection}",
      "templated" : true
    },
    "prev" : {
      "href" : "http://localhost:8080/persons?page=0&size=5{&sort,projection}",
      "templated" : true
    }
  },
  "_embedded" : {
	... data ...
  },
  "page" : {
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 1
  }
}
```

--------------------------------

### Search Resource - HEAD

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Returns whether the search resource is available. A 404 return code indicates no query method resources are available.

```APIDOC
## HEAD /api/search

### Description
Returns whether the search resource is available.

### Method
HEAD

### Endpoint
/api/search

### Response
#### Success Response (200)
- Indicates the search resource is available.

#### Error Response (404 Not Found)
- Indicates no query method resources are available.
```

--------------------------------

### Domain Type with Last Modified Date

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc

This domain type captures the last modification date using Spring Data Commons' @LastModifiedDate annotation. This allows for efficient conditional GET requests.

```java
package example.mongodb;

import org.springframework.data.annotation.LastModifiedDate;
import java.util.Date;

public class Receipt {

    @LastModifiedDate
    private Date lastModifiedDate;

    // other fields and methods
}
```

--------------------------------

### Implement ApplicationListener for Repository Events

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/events.adoc

Extend `AbstractRepositoryEventListener` to create a listener for repository events. Override specific methods like `onBeforeSave` or `onAfterDelete` to implement custom logic. Note that this approach does not distinguish between entity types by default.

```java
public class BeforeSaveEventListener extends AbstractRepositoryEventListener {

  @Override
  public void onBeforeSave(Object entity) {
    ... logic to handle inspecting the entity before the Repository saves it
  }

  @Override
  public void onAfterDelete(Object entity) {
    ... send a message that this entity has been deleted
  }
}
```

--------------------------------

### Add a Person using curl

Source: https://github.com/spring-projects/spring-data-rest/wiki/Example-API-usage-with-curl

Use a POST request with JSON data to create a new 'Person' entity. The response includes a 'Location' header with the URL of the newly created resource.

```bash
$ curl -X POST -v -d '{"name" : "John Doe"}' -H "Content-Type: application/json" http://localhost:8080/people
```

--------------------------------

### Conditional GET Request with If-Modified-Since

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc

Use the If-Modified-Since header to request a resource only if it has been modified since the specified date. This avoids re-downloading unchanged data, returning a 304 Not Modified status if no changes occurred.

```shell
curl -H "If-Modified-Since: Wed, 24 Jun 2015 20:28:15 GMT" ... 
```

--------------------------------

### Apply Excerpt Projection to Repository

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

Configure the PersonRepository to use the 'InlineAddress' excerpt projection by default. Be aware that this alters the default behavior and may cause breaking changes for existing consumers.

```java
@RepositoryRestResource(excerptProjection = InlineAddress.class)
interface PersonRepository extends CrudRepository<Person, Long> {}
```

--------------------------------

### Customizing Query Method Path with @RestResource

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

Use the @RestResource annotation on a query method to specify a custom path segment for its exposure under the 'search' resource. This example sets the path to "names".

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

  @RestResource(path = "names")
  List<Person> findByName(String name);
}
```

--------------------------------

### Association Resource - PUT

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/repository-resources.adoc

Binds a resource to an association. Supports text/uri-list media type. Returns 400 Bad Request if multiple URIs are provided for a to-one association.

```APIDOC
## PUT /api/association

### Description
Binds the resource pointed to by the given URI(s) to the association resource.

### Method
PUT

### Endpoint
/api/association

### Parameters
#### Request Body
- **URIs** (text/uri-list) - Required - URIs pointing to the resource to bind to the association.

### Response
#### Success Response (200)
- No specific fields mentioned, implies successful binding.

#### Error Response (400 Bad Request)
- When multiple URIs were given for a to-one-association.
```

--------------------------------

### Customize Item Resource URIs with Java 8+ Method References

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing-sdr.adoc

Use method references with RepositoryRestConfigurer to customize URI generation for item resources based on specific entity properties. This requires Java 8 or later.

```java
@Component
public class SpringDataRestCustomization implements RepositoryRestConfigurer {

  @Override
  public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
    config.withEntityLookup()
      .forRepository(UserRepository.class)
      .withIdMapping(User::getUsername)
      .withLookup(UserRepository::findByUsername);
  }
}
```

--------------------------------

### Add HAL Explorer Dependency in Gradle

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/tools.adoc

Add this dependency to your Gradle project to integrate the HAL Explorer. Version management is handled if you are using Spring Boot or the Spring Data BOM.

```groovy
dependencies {
    implementation 'org.springframework.data:spring-data-rest-hal-explorer'
}
```

--------------------------------

### Collection Resource with Profile Link

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/metadata.adoc

This JSON snippet shows a collection resource's HAL document, including a 'profile' link. This link points to the metadata URI for the collection's resource type.

```json
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons"
    },
    ...
    "profile" : {
      "href" : "http://localhost:8080/profile/persons"
    }
  },
  ...
}
```

--------------------------------

### View ALPS Metadata for Person Resources

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

This JSON structure represents the ALPS metadata for 'Person' resources, detailing available projections and attributes for GET requests. It's accessed via the 'profile' link from the root resource.

```json
{
  "_links": {
    "self": {
      "href": "/alps/persons"
    }
  },
  "content": [
    {
      "id": "get-person",
      "name": "person",
      "type": "SAFE",
      "rt": "#person-representation",
      "descriptors": [
        {
          "name": "projection",
          "doc": {
            "value": "The projection that shall be applied when rendering the response. Acceptable values available in nested descriptors.",
            "format": "TEXT"
          },
          "type": "SEMANTIC",
          "descriptors": [
            {
              "name": "noAddresses",
              "type": "SEMANTIC",
              "descriptors": [
                {
                  "name": "firstName",
                  "type": "SEMANTIC"
                },
                {
                  "name": "lastName",
                  "type": "SEMANTIC"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

--------------------------------

### Add HAL Explorer Dependency in Maven

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/tools.adoc

Include this dependency in your Maven project to enable the HAL Explorer. If using Spring Boot or the Spring Data BOM, the version is managed automatically.

```xml
<dependencies>
  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-rest-hal-explorer</artifactId>
  </dependency>
</dependencies>
```

--------------------------------

### Combined Path and Rel Customization Output

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/configuring-the-rest-url-path.adoc

This JSON output demonstrates how both repository-level and method-level @RestResource annotations affect the generated URIs and link names, showing the final structure for a customized query method.

```javascript
{
  "_links" : {
    "names" : {
      "href" : "http://localhost:8080/people/search/names"
    }
  }
}
```

--------------------------------

### Sort Results by Multiple Properties

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

Multiple sorting criteria can be applied by adding multiple 'sort=PROPERTY' parameters to the URL. The order of these parameters determines the priority of the sorting.

```http
http://localhost:8080/people?sort=property1,asc&sort=property2,desc
```

--------------------------------

### Configure RepositoryRestMvcConfiguration in XML

Source: https://github.com/spring-projects/spring-data-rest/wiki/Adding-Spring-Data-REST-to-an-existing-Spring-MVC-Application

Add this bean definition to your Spring MVC configuration to enable Spring Data REST. It bootstraps the necessary MVC resources for exporting Repositories.

```xml
<bean class="org.springframework.data.rest.webmvc.config.RepositoryRestMvcConfiguration"/>
```

--------------------------------

### Secure Repository with @PreAuthorize

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/security.adoc

Secures an entire repository with Spring Security's SpEL expressions. Method-level settings override repository-level settings.

```java
package org.springframework.data.rest.tests.security;

import org.springframework.security.access.prepost.PreAuthorize;

@PreAuthorize("hasRole('ROLE_USER')")
public interface PreAuthorizedOrderRepository extends CrudRepository<Order, Long> {

	@Override
	@PreAuthorize("hasRole('ROLE_ADMIN')")
	void delete(Order entity);

	@Override
	@PreAuthorize("hasRole('ROLE_ADMIN')")
	void deleteById(Long aLong);

	@Override
	@PreAuthorize("hasRole('ROLE_ADMIN')")
	void deleteAll(Iterable<? extends Order> entities);

	@Override
	@PreAuthorize("hasRole('ROLE_ADMIN')")
	void deleteAll();
}
```

--------------------------------

### Import RepositoryRestMvcConfiguration in Java

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/customizing/adding-sdr-to-spring-mvc-app.adoc

Use the @Import annotation to include RepositoryRestMvcConfiguration in your Spring MVC configuration class. This bootstraps Spring Data REST resources.

```java
import org.springframework.context.annotation.Import;
import org.springframework.data.rest.webmvc.RepositoryRestMvcConfiguration;

@Configuration
@Import(RepositoryRestMvcConfiguration.class)
public class MyApplicationConfiguration {

  …
}
```

--------------------------------

### Link a Person to a Family using curl

Source: https://github.com/spring-projects/spring-data-rest/wiki/Example-API-usage-with-curl

Use a POST request with 'text/uri-list' content type to add a person to a family's members collection. No 'Location' header is returned as multiple items can be added.

```bash
$ curl -X POST -v -d 'http://localhost:8080/people/1' -H "Content-Type: text/uri-list" http://localhost:8080/family/1/members
```

--------------------------------

### Add Custom Links to Resources

Source: https://github.com/spring-projects/spring-data-rest/wiki/REST-Exporter-Extension-Mechanism

Implement a @LinkHandler to add custom links to the "_links" section of a DTO for a specific domain type.

```java
@LinkHandler
    class PersonLinkHandler {

      @HandleResource(Person.class)
      public void addCustomLinks(Person p, List<Link> links) {
        // Add any other links
      }
  
    }
```

--------------------------------

### Register Custom Serializers and Deserializers for Jackson

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/representations.adoc

Add custom serializers and deserializers to Jackson's ObjectMapper within your Module's setupModule method. This allows for specialized handling of specific domain types during JSON conversion.

```java
@Override
public void setupModule(SetupContext context) {

  SimpleSerializers serializers = new SimpleSerializers();
  SimpleDeserializers deserializers = new SimpleDeserializers();

  serializers.addSerializer(MyEntity.class, new MyEntitySerializer());
  deserializers.addDeserializer(MyEntity.class, new MyEntityDeserializer());

  context.addSerializers(serializers);
  context.addDeserializers(deserializers);
}
```

--------------------------------

### Add Spring Data REST to Spring Boot Project with Maven

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc

Include the Spring Boot starter for Spring Data REST in your Maven pom.xml. This enables auto-configuration.

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

--------------------------------

### Handle Before Save Event for Person

Source: https://github.com/spring-projects/spring-data-rest/wiki/REST-Exporter-Extension-Mechanism

Use @RepositoryEventHandler and @HandleBeforeSave to execute logic before a Person entity is saved.

```java
@RepositoryEventHandler(Person.class)
    class PersonEventHandler {

      @HandleBeforeSave
      public void handleBeforeSave(Person p) {
  
      }
  
    }
```

--------------------------------

### Registering Abstract Type Resolver in Jackson Module

Source: https://github.com/spring-projects/spring-data-rest/wiki/Adding-custom-(de)serializers-to-Jackson's-ObjectMapper

Use this when Jackson needs to know which implementation class to instantiate for an abstract type or interface. Register a `SimpleAbstractTypeResolver` within your `Module`'s `setupModule` method.

```java
public class MyCustomModule extends SimpleModule {

	private MyCustomModule() {
		super("MyCustomModule", new Version(1, 0, 0, "SNAPSHOT"));
	}

	@Override public void setupModule(SetupContext context) {
		context.addAbstractTypeResolver(
				new SimpleAbstractTypeResolver().addMapping(MyInterface.class, MyInterfaceImpl.class)
		);
	}

}
```

--------------------------------

### Configure Spring Data REST Base Path with RepositoryRestConfigurer

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc

Implement `RepositoryRestConfigurer` as a Spring bean to programmatically set the base path. This approach is suitable for Spring Boot 1.1 or earlier, or when not using Spring Boot.

```java
@Configuration
class CustomRestMvcConfiguration {

  @Bean
  public RepositoryRestConfigurer repositoryRestConfigurer() {

    return new RepositoryRestConfigurer() {

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

--------------------------------

### Link to Single Item Resource

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/integration.adoc

Generates a link to a specific item resource identified by its class and ID. The ID must correspond to an existing resource.

```java
entityLinks.linkToItemResource(Person.class, 1)
```

--------------------------------

### Link to Specific Search Resource

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/integration.adoc

Generates a link to a specific search resource (finder method) by its 'rel' name. Supports additional parameters for paging and sorting.

```java
entityLinks.linkToSearchResource(Person.class, "findByLastName")
```

--------------------------------

### Collection Resource with Profile Link

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/metadata.adoc

A HAL collection resource includes a 'profile' link to its corresponding metadata document.

```javascript
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/persons" 
    },
    ...
    "profile" : {
      "href" : "http://localhost:8080/profile/persons" 
    }
  },
  ...
}
```

--------------------------------

### Implement Paging in Custom Query Methods

Source: https://github.com/spring-projects/spring-data-rest/wiki/Paging-and-Sorting

For custom query methods, modify the method signature to accept an additional Pageable parameter and return a Page object instead of a List. This enables paging for specific queries.

```java
@RestResource(path = "nameStartsWith", rel = "nameStartsWith")
public Page findByNameStartsWith(@Param("name") String name, Pageable p);
```

--------------------------------

### Add Spring Data REST to Spring Boot Project with Gradle

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc

Include the Spring Boot starter for Spring Data REST in your Gradle build file. This enables auto-configuration.

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

--------------------------------

### Add Spring Data REST to Gradle Project

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc

Add the `spring-data-rest-webmvc` artifact to your compile-time dependencies in a Gradle project. Replace `{version}` with the appropriate version.

```groovy
dependencies {
  … other project dependencies
  implementation("org.springframework.data:spring-data-rest-webmvc:{version}")
}
```

--------------------------------

### Adding Custom Serializers and Deserializers in Jackson Module

Source: https://github.com/spring-projects/spring-data-rest/wiki/Adding-custom-(de)serializers-to-Jackson's-ObjectMapper

Register custom serializers and deserializers for specific domain types within your `Module`'s `setupModule` method to customize JSON handling.

```java
@Override public void setupModule(SetupContext context) {
			SimpleSerializers serializers = new SimpleSerializers();
			SimpleDeserializers deserializers = new SimpleDeserializers();

			serializers.addSerializer(MyEntity.class, new MyEntitySerializer());
			deserializers.addDeserializer(MyEntity.class, new MyEntityDeserializer());

			context.addSerializers(serializers);
			context.addDeserializers(deserializers);
		}
```

--------------------------------

### Handle Before Save Event with Domain Type on Method

Source: https://github.com/spring-projects/spring-data-rest/wiki/REST-Exporter-Extension-Mechanism

Specify the domain type directly on the @HandleBeforeSave method within a @RepositoryEventHandler to handle specific entity types.

```java
@RepositoryEventHandler
    class PersonEventHandler {

      @HandleBeforeSave(Person.class)
      public void personBeforeSave(Person p) {

      }

      @HandleBeforeSave(Address.class)
      public void addressBeforeSave(Address addr) {

      }

    }
```

--------------------------------

### PersonRepository with Excerpt Projection

Source: https://github.com/spring-projects/spring-data-rest/blob/main/src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

This Java interface configures the PersonRepository to use the 'NoAddresses' projection by default when embedding Person resources into collections or related resources.

```java
@RepositoryRestResource(excerptProjection = NoAddresses.class)
interface PersonRepository extends CrudRepository<Person, Long> {}

```
Tokens:
Raw