Introduce API evolution

Show, through an old/new client/server how to implement backwards compatibility using Spring HATEOAS, thereby eliminating the need to version between domain object changes.

api-evolution/new-client/pom.xml

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>new-client</artifactId>
+    <name>Spring HATEOAS - API Evolution - New Client</name>
+    <packaging>jar</packaging>
+
+    <parent>
+        <groupId>org.springframework.hateoas.examples</groupId>
+        <artifactId>spring-hateoas-examples-api-evolution</artifactId>
+        <version>1.0.0.BUILD-SNAPSHOT</version>
+    </parent>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.hateoas.examples</groupId>
+            <artifactId>commons</artifactId>
+            <version>1.0.0.BUILD-SNAPSHOT</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-thymeleaf</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>com.jayway.jsonpath</groupId>
+            <artifactId>json-path</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+    
+</project>

api-evolution/new-client/src/main/java/org/springframework/hateoas/examples/ClientConfig.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * @author Greg Turnquist
+ */
+@Configuration
+public class ClientConfig {
+
+	@Bean
+	public RestTemplate restTemplate() {
+		return new RestTemplate();
+	}
+}

api-evolution/new-client/src/main/java/org/springframework/hateoas/examples/Employee.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import org.springframework.hateoas.Identifiable;
+
+/**
+ * An updated domain object on the client side. It doesn't need all the backward compatible bits that the new
+ * server needs (unless this becomes a service of its own).
+ * 
+ * @author Greg Turnquist
+ */
+@Data
+@NoArgsConstructor
+class Employee implements Identifiable<Long> {
+
+	private Long id;
+	private String firstName;
+	private String lastName;
+	private String role;
+
+	Employee(String firstName, String lastName, String role) {
+
+		this.firstName = firstName;
+		this.lastName = lastName;
+		this.role = role;
+	}
+}

api-evolution/new-client/src/main/java/org/springframework/hateoas/examples/HomeController.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import java.net.URI;
+import java.net.URISyntaxException;
+
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.Resource;
+import org.springframework.hateoas.Resources;
+import org.springframework.hateoas.client.Traverson;
+import org.springframework.hateoas.mvc.TypeReferences.ResourcesType;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * A web controller that serves up client data found on a remote REST service.
+ *
+ * @author Greg Turnquist
+ */
+@Controller
+public class HomeController {
+
+	private static final String REMOTE_SERVICE_ROOT_URI = "http://localhost:9000";
+
+	private final RestTemplate rest;
+
+	public HomeController(RestTemplate restTemplate) {
+		this.rest = restTemplate;
+	}
+
+	/**
+	 * Get a listing of ALL {@link Employee}s by querying the remote services' root URI, and then
+	 * "hopping" to the {@literal employees} rel.
+	 *
+	 * NOTE: Also create a form-backed {@link Employee} object to allow creating a new entry with
+	 * the Thymeleaf template.
+	 *
+	 * @param model
+	 * @return
+	 * @throws URISyntaxException
+	 */
+	@GetMapping
+	public String index(Model model) throws URISyntaxException {
+
+		Traverson client = new Traverson(new URI(REMOTE_SERVICE_ROOT_URI), MediaTypes.HAL_JSON);
+		Resources<Resource<Employee>> employees = client
+			.follow("employees")
+			.toObject(new ResourcesType<Resource<Employee>>(){});
+
+		model.addAttribute("employee", new Employee());
+		model.addAttribute("employees", employees);
+
+		return "index";
+	}
+
+	/**
+	 * Instead of putting the creation link from the remote service in the template (a security concern),
+	 * have a local route for {@literal POST} requests. Gather up the information, and form a remote call,
+	 * using {@link Traverson} to fetch the {@literal employees} {@link Link}.
+	 *
+	 * Once a new employee is created, redirect back to the root URL.
+	 *
+	 * @param employee
+	 * @return
+	 * @throws URISyntaxException
+	 */
+	@PostMapping("/employees")
+	public String newEmployee(@ModelAttribute Employee employee) throws URISyntaxException {
+
+		Traverson client = new Traverson(new URI(REMOTE_SERVICE_ROOT_URI), MediaTypes.HAL_JSON);
+		Link employeesLink = client
+			.follow("employees")
+			.asLink();
+
+		this.rest.postForEntity(employeesLink.expand().getHref(), employee, Employee.class);
+
+		return "redirect:/";
+	}
+}

api-evolution/new-client/src/main/java/org/springframework/hateoas/examples/NewClientApplication.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Greg Turnquist
+ */
+@SpringBootApplication
+public class NewClientApplication {
+
+	public static void main(String... args) {
+		SpringApplication.run(NewClientApplication.class, args);
+	}
+
+}

api-evolution/new-client/src/main/resources/templates/index.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en" xmlns:th="http://www.thymeleaf.org">
+<head>
+    <meta charset="UTF-8" />
+    <title>Spring HATEOAS Examples - Original Client</title>
+    <style>
+        table {
+            border-collapse: collapse;
+        }
+
+        td, th {
+            border: 1px solid #999;
+            padding: 0.5rem;
+            text-align: left;
+        }
+    </style>
+</head>
+<body>
+    <h1>Spring HATEOAS Examples - New Client</h1>
+
+    <p>
+        This is the <b>new client</b>. It can only talk to the <b>new server</b>. If it were to become a REST service
+        as well, we'd have to design a little extra in order to support that as well.
+    </p>
+
+    <table>
+        <thead>
+        <tr>
+            <th>First Name</th><th>Last Name</th><th>Role</th><th>Links</th>
+        </tr>
+        </thead>
+        <tbody>
+            <tr th:each="employee : ${employees}">
+                <td th:text="${employee.content.firstName}" />
+                <td th:text="${employee.content.lastName}" />
+                <td th:text="${employee.content.role}" />
+                <td>
+                    <ul>
+                        <li th:each="link : ${employee.links}">
+                            <a th:text="${link.rel}" th:href="${link.href}" />
+                        </li>
+                    </ul>
+                </td>
+            </tr>
+        </tbody>
+    </table>
+    
+    <form method="post" th:action="@{/employees}" th:object="${employee}">
+        <input type="text" th:field="*{firstName}" placeholder="Name" />
+        <input type="text" th:field="*{lastName}" placeholder="Name" />
+        <input type="text" th:field="*{role}" placeholder="Role"/>
+        <input type="submit" value="Submit" />
+    </form>
+</body>
+</html>

api-evolution/new-server/pom.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>new-server</artifactId>
+    <name>Spring HATEOAS - API Evolution - New Server</name>
+    <version>1.0.0.BUILD-SNAPSHOT</version>
+
+    <parent>
+        <groupId>org.springframework.hateoas.examples</groupId>
+        <artifactId>spring-hateoas-examples-api-evolution</artifactId>
+        <version>1.0.0.BUILD-SNAPSHOT</version>
+    </parent>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/Employee.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import java.util.Arrays;
+
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import org.springframework.hateoas.Identifiable;
+import org.springframework.util.StringUtils;
+
+/**
+ * An updated domain object where {@literal name} has been replaced by {@literal firstName} and {@literal} lastName.
+ * To easy migration, we need to support the old {@literal name} field with a getter and a setter.
+ * 
+ * @author Greg Turnquist
+ */
+@Data
+@NoArgsConstructor
+@Entity
+class Employee implements Identifiable<Long> {
+
+	@Id @GeneratedValue
+	private Long id;
+	private String firstName;
+	private String lastName;
+	private String role;
+
+	Employee(String firstName, String lastName, String role) {
+
+		this.firstName = firstName;
+		this.lastName = lastName;
+		this.role = role;
+	}
+
+	/**
+	 * Just merged {@literal firstName} and {@literal lastName} together.
+	 * 
+	 * @return
+	 */
+	public String getName() {
+		return this.firstName + " " + this.lastName;
+	}
+
+	/**
+	 * Split things up, and assign the first token to {@literal firstName} with everything else to {@literal lastName}.
+	 *
+	 * @param wholeName
+	 */
+	public void setName(String wholeName) {
+
+		String[] parts = wholeName.split(" ");
+		this.firstName = parts[0];
+		if (parts.length > 1) {
+			this.lastName = StringUtils.arrayToDelimitedString(Arrays.copyOfRange(parts, 1, parts.length), " ");
+		} else {
+			this.lastName = "";
+		}
+	}
+}

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/EmployeeController.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*;
+
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.Resource;
+import org.springframework.hateoas.ResourceSupport;
+import org.springframework.hateoas.Resources;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author Greg Turnquist
+ */
+@RestController("/api")
+class EmployeeController {
+
+	private final EmployeeRepository repository;
+	private final EmployeeResourceAssembler assembler;
+
+	EmployeeController(EmployeeRepository repository, EmployeeResourceAssembler assembler) {
+
+		this.repository = repository;
+		this.assembler = assembler;
+	}
+
+	@GetMapping(value = "/", produces = MediaTypes.HAL_JSON_VALUE)
+	public ResourceSupport root() {
+
+		ResourceSupport rootResource = new ResourceSupport();
+		
+		rootResource.add(
+			linkTo(methodOn(EmployeeController.class).root()).withSelfRel(),
+			linkTo(methodOn(EmployeeController.class).findAll()).withRel("employees"));
+
+		return rootResource;
+	}
+
+	@GetMapping(value = "/employees", produces = MediaTypes.HAL_JSON_VALUE)
+	public Resources<Resource<Employee>> findAll() {
+		return assembler.toResources(repository.findAll());
+	}
+
+	@PostMapping("/employees")
+	public ResponseEntity<Resource<Employee>> newEmployee(@RequestBody Employee employee) {
+
+		Employee savedEmployee = repository.save(employee);
+
+		return ResponseEntity
+			.created(linkTo(methodOn(EmployeeController.class).findOne(savedEmployee.getId())).toUri())
+			.body(assembler.toResource(savedEmployee));
+	}
+
+	@GetMapping(value = "/employees/{id}", produces = MediaTypes.HAL_JSON_VALUE)
+	public Resource<Employee> findOne(@PathVariable Long id) {
+		return assembler.toResource(repository.findOne(id));
+	}
+
+}

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/EmployeeRepository.java

@@ -0,0 +1,24 @@
+package org.springframework.hateoas.examples;/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import org.springframework.data.repository.CrudRepository;
+
+/**
+ * @author Greg Turnquist
+ */
+interface EmployeeRepository extends CrudRepository<Employee, Long> {
+
+}

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/EmployeeResourceAssembler.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.hateoas.SimpleIdentifiableResourceAssembler;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author Greg Turnquist
+ */
+@Component
+class EmployeeResourceAssembler extends SimpleIdentifiableResourceAssembler<Employee> {
+
+	EmployeeResourceAssembler() {
+		super(EmployeeController.class);
+	}
+}

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/InitDatabase.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.context.annotation.Bean;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author Greg Turnquist
+ */
+@Component
+class InitDatabase {
+
+	private final EmployeeRepository repository;
+
+	InitDatabase(EmployeeRepository repository) {
+		this.repository = repository;
+	}
+
+	@Bean
+	CommandLineRunner loadEmployees() {
+		return args -> {
+			repository.save(new Employee("Frodo", "Baggins", "ring bearer"));
+			repository.save(new Employee("Bilbo", "Baggins", "burglar"));
+		};
+	}
+
+}

api-evolution/new-server/src/main/java/org/springframework/hateoas/examples/NewServerApplication.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Greg Turnquist
+ */
+@SpringBootApplication
+public class NewServerApplication {
+
+	public static void main(String... args) {
+		SpringApplication.run(NewServerApplication.class, args);
+	}
+
+}

api-evolution/new-server/src/main/resources/application.yml

@@ -0,0 +1,2 @@
+server:
+  port: 9000

api-evolution/original-client/pom.xml

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>original-client</artifactId>
+    <name>Spring HATEOAS - API Evolution - Original Client</name>
+    <packaging>jar</packaging>
+
+    <parent>
+        <groupId>org.springframework.hateoas.examples</groupId>
+        <artifactId>spring-hateoas-examples-api-evolution</artifactId>
+        <version>1.0.0.BUILD-SNAPSHOT</version>
+    </parent>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.hateoas.examples</groupId>
+            <artifactId>commons</artifactId>
+            <version>1.0.0.BUILD-SNAPSHOT</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-thymeleaf</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>com.jayway.jsonpath</groupId>
+            <artifactId>json-path</artifactId>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+
+
+</project>

api-evolution/original-client/src/main/java/org/springframework/hateoas/examples/ClientConfig.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * @author Greg Turnquist
+ */
+@Configuration
+public class ClientConfig {
+
+	@Bean
+	public RestTemplate restTemplate() {
+		return new RestTemplate();
+	}
+}

api-evolution/original-client/src/main/java/org/springframework/hateoas/examples/Employee.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import org.springframework.hateoas.Identifiable;
+
+/**
+ * @author Greg Turnquist
+ */
+@Data
+@NoArgsConstructor
+class Employee implements Identifiable<Long> {
+
+	private Long id;
+	private String name;
+	private String role;
+
+	Employee(String name, String role) {
+		
+		this.name = name;
+		this.role = role;
+	}
+}

api-evolution/original-client/src/main/java/org/springframework/hateoas/examples/HomeController.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import java.net.URI;
+import java.net.URISyntaxException;
+
+import org.springframework.hateoas.Link;
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.Resource;
+import org.springframework.hateoas.Resources;
+import org.springframework.hateoas.client.Traverson;
+import org.springframework.hateoas.mvc.TypeReferences.ResourcesType;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.ModelAttribute;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.client.RestTemplate;
+
+/**
+ * A web controller that serves up client data found on a remote REST service.
+ *
+ * @author Greg Turnquist
+ */
+@Controller
+public class HomeController {
+
+	private static final String REMOTE_SERVICE_ROOT_URI = "http://localhost:9000";
+
+	private final RestTemplate rest;
+
+	public HomeController(RestTemplate restTemplate) {
+		this.rest = restTemplate;
+	}
+
+	/**
+	 * Get a listing of ALL {@link Employee}s by querying the remote services' root URI, and then
+	 * "hopping" to the {@literal employees} rel.
+	 *
+	 * NOTE: Also create a form-backed {@link Employee} object to allow creating a new entry with
+	 * the Thymeleaf template.
+	 *
+	 * @param model
+	 * @return
+	 * @throws URISyntaxException
+	 */
+	@GetMapping
+	public String index(Model model) throws URISyntaxException {
+
+		Traverson client = new Traverson(new URI(REMOTE_SERVICE_ROOT_URI), MediaTypes.HAL_JSON);
+		Resources<Resource<Employee>> employees = client
+			.follow("employees")
+			.toObject(new ResourcesType<Resource<Employee>>(){});
+
+		model.addAttribute("employee", new Employee());
+		model.addAttribute("employees", employees);
+
+		return "index";
+	}
+
+	/**
+	 * Instead of putting the creation link from the remote service in the template (a security concern),
+	 * have a local route for {@literal POST} requests. Gather up the information, and form a remote call,
+	 * using {@link Traverson} to fetch the {@literal employees} {@link Link}.
+	 *
+	 * Once a new employee is created, redirect back to the root URL.
+	 *
+	 * @param employee
+	 * @return
+	 * @throws URISyntaxException
+	 */
+	@PostMapping("/employees")
+	public String newEmployee(@ModelAttribute Employee employee) throws URISyntaxException {
+
+		Traverson client = new Traverson(new URI(REMOTE_SERVICE_ROOT_URI), MediaTypes.HAL_JSON);
+		Link employeesLink = client
+			.follow("employees")
+			.asLink();
+
+		this.rest.postForEntity(employeesLink.expand().getHref(), employee, Employee.class);
+
+		return "redirect:/";
+	}
+}

api-evolution/original-client/src/main/java/org/springframework/hateoas/examples/OriginalClientApplication.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Greg Turnquist
+ */
+@SpringBootApplication
+public class OriginalClientApplication {
+
+	public static void main(String... args) {
+		SpringApplication.run(OriginalClientApplication.class, args);
+	}
+
+}

api-evolution/original-client/src/main/resources/templates/index.html

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en" xmlns:th="http://www.thymeleaf.org">
+<head>
+    <meta charset="UTF-8" />
+    <title>Spring HATEOAS Examples - Original Client</title>
+    <style>
+        table {
+            border-collapse: collapse;
+        }
+
+        td, th {
+            border: 1px solid #999;
+            padding: 0.5rem;
+            text-align: left;
+        }
+    </style>
+</head>
+<body>
+    <h1>Spring HATEOAS Examples - Original Client</h1>
+
+    <p>
+        This is the <b>original client</b>, and it was coded to talk to the <b>original server</b>,
+        but with a little design and thought, we can have it to talk to the <b>new server</b> as well!
+    </p>
+
+    <table>
+        <thead>
+        <tr>
+            <th>Name</th><th>Role</th><th>Links</th>
+        </tr>
+        </thead>
+        <tbody>
+            <tr th:each="employee : ${employees}">
+                <td th:text="${employee.content.name}" />
+                <td th:text="${employee.content.role}" />
+                <td>
+                    <ul>
+                        <li th:each="link : ${employee.links}">
+                            <a th:text="${link.rel}" th:href="${link.href}" />
+                        </li>
+                    </ul>
+                </td>
+            </tr>
+        </tbody>
+    </table>
+    
+    <form method="post" th:action="@{/employees}" th:object="${employee}">
+        <input type="text" th:field="*{name}" placeholder="Name" />
+        <input type="text" th:field="*{role}" placeholder="Role"/>
+        <input type="submit" value="Submit" />
+    </form>
+</body>
+</html>

api-evolution/original-server/pom.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>original-server</artifactId>
+    <name>Spring HATEOAS - API Evolution - Original Server</name>
+    <packaging>jar</packaging>
+
+    <parent>
+        <groupId>org.springframework.hateoas.examples</groupId>
+        <artifactId>spring-hateoas-examples-api-evolution</artifactId>
+        <version>1.0.0.BUILD-SNAPSHOT</version>
+    </parent>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
+    
+</project>

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/Employee.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import javax.persistence.Entity;
+import javax.persistence.GeneratedValue;
+import javax.persistence.Id;
+
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import org.springframework.hateoas.Identifiable;
+
+/**
+ * @author Greg Turnquist
+ */
+@Data
+@NoArgsConstructor
+@Entity
+class Employee implements Identifiable<Long> {
+
+	@Id @GeneratedValue
+	private Long id;
+	private String name;
+	private String role;
+
+	Employee(String name, String role) {
+		
+		this.name = name;
+		this.role = role;
+	}
+}

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/EmployeeController.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*;
+
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.Resource;
+import org.springframework.hateoas.ResourceSupport;
+import org.springframework.hateoas.Resources;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * @author Greg Turnquist
+ */
+@RestController
+class EmployeeController {
+
+	private final EmployeeRepository repository;
+	private final EmployeeResourceAssembler assembler;
+
+	EmployeeController(EmployeeRepository repository, EmployeeResourceAssembler assembler) {
+
+		this.repository = repository;
+		this.assembler = assembler;
+	}
+
+	@GetMapping(value = "/", produces = MediaTypes.HAL_JSON_VALUE)
+	public ResourceSupport root() {
+
+		ResourceSupport rootResource = new ResourceSupport();
+		
+		rootResource.add(
+			linkTo(methodOn(EmployeeController.class).root()).withSelfRel(),
+			linkTo(methodOn(EmployeeController.class).findAll()).withRel("employees"));
+
+		return rootResource;
+	}
+
+	@GetMapping(value = "/employees", produces = MediaTypes.HAL_JSON_VALUE)
+	public Resources<Resource<Employee>> findAll() {
+		return assembler.toResources(repository.findAll());
+	}
+
+	@PostMapping("/employees")
+	public ResponseEntity<Resource<Employee>> newEmployee(@RequestBody Employee employee) {
+
+		Employee savedEmployee = repository.save(employee);
+		
+		return ResponseEntity
+			.created(linkTo(methodOn(EmployeeController.class).findOne(savedEmployee.getId())).toUri())
+			.body(assembler.toResource(savedEmployee));
+	}
+
+	@GetMapping(value = "/employees/{id}", produces = MediaTypes.HAL_JSON_VALUE)
+	public Resource<Employee> findOne(@PathVariable Long id) {
+		return assembler.toResource(repository.findOne(id));
+	}
+
+}

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/EmployeeRepository.java

@@ -0,0 +1,24 @@
+package org.springframework.hateoas.examples;/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import org.springframework.data.repository.CrudRepository;
+
+/**
+ * @author Greg Turnquist
+ */
+interface EmployeeRepository extends CrudRepository<Employee, Long> {
+
+}

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/EmployeeResourceAssembler.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.hateoas.SimpleIdentifiableResourceAssembler;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author Greg Turnquist
+ */
+@Component
+class EmployeeResourceAssembler extends SimpleIdentifiableResourceAssembler<Employee> {
+
+	EmployeeResourceAssembler() {
+		super(EmployeeController.class);
+	}
+}

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/InitDatabase.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.context.annotation.Bean;
+import org.springframework.stereotype.Component;
+
+/**
+ * @author Greg Turnquist
+ */
+@Component
+class InitDatabase {
+
+	private final EmployeeRepository repository;
+
+	InitDatabase(EmployeeRepository repository) {
+		this.repository = repository;
+	}
+
+	@Bean
+	CommandLineRunner loadEmployees() {
+		return args -> {
+			repository.save(new Employee("Frodo", "ring bearer"));
+			repository.save(new Employee("Bilbo", "burglar"));
+		};
+	}
+
+}

api-evolution/original-server/src/main/java/org/springframework/hateoas/examples/OriginalServerApplication.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2017 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.examples;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * @author Greg Turnquist
+ */
+@SpringBootApplication
+public class OriginalServerApplication {
+
+	public static void main(String... args) {
+		SpringApplication.run(OriginalServerApplication.class, args);
+	}
+
+}

api-evolution/original-server/src/main/resources/application.yml

@@ -0,0 +1,2 @@
+server:
+  port: 9000

api-evolution/pom.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+		 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<artifactId>spring-hateoas-examples-api-evolution</artifactId>
+	<name>Spring HATEOAS - API Evolution</name>
+	<packaging>pom</packaging>
+
+	<parent>
+		<groupId>org.springframework.hateoas.examples</groupId>
+		<artifactId>spring-hateoas-examples</artifactId>
+		<version>1.0.0.BUILD-SNAPSHOT</version>
+	</parent>
+
+	<modules>
+		<module>original-server</module>
+		<module>original-client</module>
+		<module>new-server</module>
+		<module>new-client</module>
+	</modules>
+
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.hateoas.examples</groupId>
+			<artifactId>commons</artifactId>
+			<version>1.0.0.BUILD-SNAPSHOT</version>
+		</dependency>
+	</dependencies>
+
+</project>

basics/pom.xml

@@ -14,5 +14,21 @@
 		<version>1.0.0.BUILD-SNAPSHOT</version>
 	</parent>
 
+	<dependencies>
+		<dependency>
+			<groupId>org.springframework.hateoas.examples</groupId>
+			<artifactId>commons</artifactId>
+			<version>1.0.0.BUILD-SNAPSHOT</version>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<groupId>org.springframework.boot</groupId>
+				<artifactId>spring-boot-maven-plugin</artifactId>
+			</plugin>
+		</plugins>
+	</build>
 
 </project>

commons/pom.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>commons</artifactId>
+    <name>Spring HATEOAS - Examples - Commons</name>
+    <description>Components that may eventually join Spring HATEOAS</description>
+
+    <parent>
+        <groupId>org.springframework.hateoas.examples</groupId>
+        <artifactId>spring-hateoas-examples</artifactId>
+        <version>1.0.0.BUILD-SNAPSHOT</version>
+    </parent>
+
+
+</project>

commons/src/test/java/org/springframework/hateoas/SimpleResourceAssemblerTest.java

@@ -22,6 +22,7 @@ import static org.hamcrest.Matchers.*;
 import java.util.Arrays;
 
 import lombok.Data;
+import org.hamcrest.MatcherAssert;
 import org.hamcrest.Matchers;
 import org.junit.Test;
 
@@ -45,7 +46,7 @@ public class SimpleResourceAssemblerTest {
 		Resources<Resource<Employee>> resources = assembler.toResources(Arrays.asList(new Employee("Frodo")));
 		assertThat(resources.getContent(), hasSize(1));
 		assertThat(resources.getContent(), Matchers.<Resource<Employee>>contains(new Resource(new Employee("Frodo"))));
-		assertThat(resources.getLinks(), is(Matchers.<Link>empty()));
+		MatcherAssert.assertThat(resources.getLinks(), is(Matchers.<Link>empty()));
 
 		assertThat(resources.getContent().iterator().next(), is(new Resource(new Employee("Frodo"))));
 	}

pom.xml

@@ -44,7 +44,9 @@
 	</parent>
 
 	<modules>
+		<module>commons</module>
 		<module>basics</module>
+		<module>api-evolution</module>
 	</modules>
 
 	<properties>
@@ -132,15 +134,6 @@
 		</dependency>
 	</dependencies>
 
-	<build>
-		<plugins>
-			<plugin>
-				<groupId>org.springframework.boot</groupId>
-				<artifactId>spring-boot-maven-plugin</artifactId>
-			</plugin>
-		</plugins>
-	</build>
-
 	<repositories>
 		<repository>
 			<id>spring-libs-snapshot</id>