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-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