HouseRentals Assignment 2: API

package your implementation along proper module boundaries

Create your overall project as two (or more) Maven modules under a single parent

Define the svc module as a Web Application (dependency on spring-boot-starter-web).

Add a @SpringBootApplication class to the app module (already provided in starter for initial demo).

Once constructed, the modules should be able to

package your implementation along proper module boundaries

Pick a Maven hierarchical groupId for your modules that is unique to your overall work on this assignment.

design a set of Data Transfer Objects (DTOs) to render information from and to the service

define a Java class content type mappings to customize marshalling/unmarshalling

specify content types consumed and produced by a controller

specify content types accepted by a client

Create a DTO class to represent HouseRental. Use the attributes in the diagram above and descriptions below as candidate properties for each class.

Create a HouseRentalListDTO class to provide a typed collection of HouseRentalDTO.

Map each DTO class to:

Create a unit test to verify your new DTO type(s) can be marshalled/unmarshalled to/from the targeted serialization type.

API TODO: Annotate controller methods to consume and produce supported content type(s) when they are implemented.

API TODO: Update clients used in unit tests to explicitly only accept supported content type(s) when they are implemented.

design a set of Data Transfer Objects (DTOs) to render information from and to the service

define a Java class content type mappings to customize marshalling/unmarshalling

API TODO: specify content types consumed and produced by a controller

API TODO: specify content types accepted by a client

This portion of the assignment alone primarily produces a set of information classes that make up the primary vocabulary of your API and service classes.

Use of lombok is highly encouraged here and can tremendously reduce the amount of code you write for these classes

The Java Period class can easily calculate age in years between two LocalDates. A TimePeriod class has been provided in the DTO package to aggregate startDate and endDate LocalDates together and to provide convenience methods related to those values.

The houserenters-support-api-client module also provides a HouseDTOFactory, RenterDTOFactory, and StreetAddressDTOFactory that makes it easy for tests and other demonstration code to quickly assembly example instances. You are encouraged to follow that pattern.

The houserenters-support-api-client test cases for House and Renter demonstrate marshalling and unmarshalling DTO classes within a JUnit test. You should create a similar test of your HouseRenterDTO class to satisfy the testing requirement. Note that those tests leverage a JsonUtil class that is part of the class utility examples and simplifies example use of the Jackson JSON parser.

The houserenters-support-api-client and supplied starter unit tests make use of JUnit @ParameterizedTest — which allows a single JUnit test method to be executed N times with variable parameters — pretty cool feature. Try it.

Supporting multiple content types is harder than it initially looks — especially when trying to mix different libraries. WebClient does not currently support Jackson XML and will attempt to resort to using JAXB in the client. I provide an example of this later in the semester (Spring Data JPA End-to-End) and advise you to address the optional XML mapping last after all other requirements of the assignment are complete. If you do attempt to tackle both XML and WebClient together, know to use JacksonXML mappings for the server-side and JAXB mappings for the client-side.

identify resources

define a URI for a resource

define the proper method for a call against a resource

identify appropriate response code family and value to use in certain circumstances

Houses (provided) - an individual house that can be part of a house rental

Renters (provided) - identification for a person that may participate in a house rental

HouseRentals (your assignment) - a transaction for one House and one Renter for a unique period of time

Identify your base resource(s) and sub-resource(s)

Identify the @RestController methods required to represent the following actions for HouseRental. Assign them specific URIs and HTTP methods.

CLIENT TODO: Identify the response status codes to be returned for each of the actions

identify resources

define a URI for a resource

define the proper method for a call against a resource

CLIENT TODO: identify appropriate response code family and value to use in certain circumstances

This portion of the assignment alone should produce a @RestController class with annotated methods that statically define your API interface (possibly missing content details). There is nothing to run or test in this portion alone.

A simple and useful way of expressing your URIs can be through defining a set of public static attributes expressing the collection and individual instance of the resource type.

String (RESOURCE)S_PATH="(path)";
String (RESOURCE)_PATH="(path)/{identifier(s)}";

If you start with this portion, you may find it helpful to

The details of the HouseRental will be performed server-side — based upon IDs and properties provided by the client and the House and Renter values found server-side. The client never provides more than an ID for an House or Renter and if it does — the server-side must ignore and rely on the server-side source for details.

There is nothing to code up relative to response codes at this point. However:

implement a service method with Spring MVC synchronous annotated controller

implement a client using RestTemplate, RestClient, or Spring Http Interface

pass parameters between client and service over HTTP

return HTTP response details from service

access HTTP response details in client

Implement stub behavior in the controller class as necessary to complete the example end-to-end calls.

HouseDTO newRental = HouseDTO.builder().id("1").build()
URI location = ServletUriComponentsBuilder.fromCurrentRequestUri()
        .replacePath(HOUSERENTAL_PATH)
        .build("1");
return ResponseEntity.created(location).body(newRental);

Implement a unit integration test to demonstrate a success path

implement a service method with Spring MVC synchronous annotated controller

implement a client using RestTemplate or RestClient

pass parameters between client and service over HTTP

return HTTP response details from service

access HTTP response details in client

The required end-to-end tests in the last section require many specific success and failure test scenarios. View this portion of the assignment as just an early draft work of those scenarios. If you have completed the end-to-end tests, you have completed this portion of the assignment.

Your DTO class(es) have been placed in your Client module in a separate section of this assignment. You may want to add an optional API client class to that Client module — to encapsulate the details of the HTTP calls. The houserenters-support-client module contains example client API classes for Houses and Renters using RestTemplate and Spring HTTP Interface.

Avoid placing extensive business logic into the stub portion of the assignment. The controller method details are part of a separate section of this assignment.

This portion of the assignment alone should produce a simple, but significant demonstration of client/API communications (success and failure) using HTTP and service as the model for implementing additional resource actions.

Inject the dependencies for the test from the Spring context. Anything that depends on the server’s port number must be delayed (@Lazy)

//ProvidedApiHouseRenterTestConfiguration.java
@Bean @Lazy (2)
@ConditionalOnMissingBean(name="testServerConfig")
public ServerConfig testServerConfig(ServerConfig serverConfig,
                                    @LocalServerPort int port) { (1)
    return serverConfig./*...*/.withPort(port).build();
}

@Bean @Lazy (3)
public HousesAPI housesAPI(RestTemplate restTemplate, ServerConfig testServerConfig) {
    return new HousesAPIClient(restTemplate, testServerConfig, MediaType.APPLICATION_JSON);
}

//HouseRentalsAPINTest.java
@SpringBootTest(...webEnvironment=...
public class HouseRentalsAPINTest {
    @Autowired
    private HousesAPI houseAPI;

implement a service class to encapsulate business logic

turn @RestController class into a facade and delegate business logic details to an injected service class

implement an error reporting strategy

Implement a HouseRentalDTORepository interface and implementation component to simulate necessary behavior (e.g., save, findById, find) for the base HouseRentalDTO resource type. Don’t go overboard here. We just need some place to generate IDs and hold the data in memory.

Implement a HouseRental service to implement actions and enforce business logic on the base resources

Design a means for service calls to

Design a means for Controller calls to

Integrate services into controller components

Implement a unit integration test to demonstrate at least one success and error path

implement a service class to encapsulate business logic

turn @RestController class into a facade and delegate business logic details to an injected service class

implement an error reporting strategy

This portion of the assignment alone primarily provides an implementation pattern for how services will report successful and unsuccessful requests and how the API will turn that into a meaningful HTTP response that the client can access.

The houserenters-support-api-svc module contains a set of example DTO Repository Stubs.

You are required to use the Pageable and Page classes (from the org.springframework.data.domain Java package) for paging methods in your finder method(s) — to be forward compatible with later assignments that make use of Spring Data. You can find example use of Pageable and Page (and PageImpl) in House and Renter examples.

It is highly recommended that exceptions be used between the service and controller layers to identify error scenarios and specific exceptions be used to help identify which kind of error is occurring in order to report accurate status to the client. Leave non-exception paths for successful results. The Houses and Renters example leverage the exceptions defined in the ejava-dto-util module. You are free to define your own.

It is highly recommended that ExceptionHandlers and RestExceptionAdvice be used to handle exceptions thrown and report status. The Houses and Renters example leverage the ExceptionHandlers from the ejava-web-util module. You are free to define your own.

Implement the above scenarios within one or more integration unit tests.

Name the tests such that they are picked up and executed by the Surefire test phase of the maven build.

Turn in a cleaned source tree of the project under a single root parent project. The House and Renter modules do not need to be included.

The source tree should be ready to build in an external area that has access to the ejava-nexus-snaphots repository.

create an integration test that verifies a successful scenario

create an integration test that verifies a failure scenario

Place behavior in the proper place