In this homework, you will implement a REST API for RentIt’s information system. This REST API will later be used in the interaction with one (or several) front-end application(s): the one used by RentIt’s employees to process purchase orders, or the one allowing employees to schedule maintenance tasks.
In fact, we have been implementing parts of the REST API with parts taken from the lecture slides and throughout the lab sessions. To illustrate the API, we will use in this documents some UML sequence diagrams. Hence, let us start with the one shown below:
The sequence diagram shows how the customer can query the plant catalog using a first REST interaction. For instance, we could be using a request like:
GET /api/sales/plants?name=exc&startDate=2019-03-20&endDate=2019-03-24
to which RentIt’s information system will reply, returning the list of excavators that are available for the period 20-24 March 2019. Assuming the list is not empty, the idea is that the customer would then submit a request to create a purchase order, with one of the plants in the returned list, the corresponding rental period and some additional information. To that end, a REST interaction will be used similar to:
POST /api/sales/orders
which would also include a JSON file with the information of the purchase
order. When purchase order is create, a new entry on the database is
inserted with its status set to PENDING. Remember that, as a result of
a POST operation, we expect that a reference to the newly created purchase
order is included using the header location (e.g. Location: /api/sales/orders/123)
and a status code 201.
At this point, we expect that an employee within RentIt would review all the pending purchase orders and allocate a plant inventory item (via a plant reservation) to each of them, whenever possible. The customer will use the URL returned by the REST interaction above to periodically query the status of a purchase order (we expect that a purchase order would eventually change from status PENDING to OPEN or REJECTED). Please note that we assume that the decision of whether to assign one plant to a purchase order or not is based on business rules that require the intervention of one employee. That is the reason why we do not automatically allocate the plants.
The goal of this homework is to complete the design and implementation of two different approaches to purchase order/plant allocation.
Design variants
Plant preallocation
The first variant that you would have to explore is specified by means of the following sequence diagram.
The idea is that the RentIt’s employee starts by querying the list purchase orders that have status of PENDING. It is in this step where we can imaging that the employee would apply a heuristic to choose one of the purchase orders for processing (e.g. it could be by applying a first-come/first-serve order, based on the customer’s credit history, etc.) In this case, the REST interaction would serve to try to allocate one plant inventory item for the purchase order selected by the employee. If the system finds at least one available plant, the system will reserve it (i.e. the first one in the returned list) and update the purchase order with the reservation and a new status, i.e. PREALLOCATED. If no available plant is found for this purchase order, we expect that the system would set the purchase order to status REJECTED. The REST interaction would finish by reporting the outcome of the preallocation (i.e. 201 to notify a successful preallocation or 409 otherwise).
In case of a successful preallocation, the employee would have the opportunity to either confirm or reject the allocation. The rationale is that the employee could first try to preallocate plants to a batch of purchase orders to identify potential problems and change the allocation if needed. The following sequence diagram show how a plant preallocation can be confirmed or rejected by the employee.
Based on the requeriments above you will perform the following tasks:
Tasks-
Identify the operations implied by the sequence diagram that should be mapped into REST interactions.
-
Reorganize the state model associated with the resource purchase order. Submit a PDF file containing the new state model.
-
Summarize the REST API in the form of a table that presents the HTTP verb, URI, "Relation", states in the state model and a brief description of the operation. See for example the table in slide 13 of Lecture 6.
Direct plant allocation
In this variant, the idea is that the RentIt’s employee will process one pending PO at a time. To this end, the employee will query the inventory to retrieve the list of plant inventory items that are suitable for this purchase order (i.e. items that correspond to the required entry and are available for the rental period specified by the purchase order), select one of the items in the list and accept the purchase order with the previously selected item. Please note that in this case, the acceptance of the purchase order will not only change the status of the purchase order but will also allocate the selected plant to the purchase order. Henceforth, the acceptance entails the creation of a plant reservation. To complete the scenario, we assume that the employee would have the option to reject a purchase order (e.g. when no available plant is found) by means of a REST interaction.
Tasks-
Prepare the documents capturing your design for this variant (include them in a PDF file)
-
Sequence diagrams
-
State model
-
Table summarizing the REST API
-
-
Implement the REST API, by extending the Spring application used in the lab sessions.
-
Implement a validation service for purchase orders. The validation is performed every time we are about to create or update a purchase order and the diagnostic of the problems must be included in the body of the response to the REST interaction (along with the corresponding status code). For this point, you should use the Spring validation framework (cf. see) as sketched in the slides of the lecture.
-
Write tests corresponding to the following scenarios (these tests are very minimal, you should write more tests to verify your application):
-
A recently created PO must have a valid reference to a plant inventory entry, a valid rental period (e.g. start < end date, period must be in the future, and both dates must be different from null),
-
Once the PO is stored in the database, the PO must always have a valid identifier
-
An OPEN/CLOSED PO must have a valid plant reservation (e.g. the period of the reservation must be consistent with the PO rental period, the reservation must be connected with an plant inventory item that was available before the reservation)
-
An OPEN/CLOSED PO must have a valid total cost (e.g. positive value)
-
You must submit the link to your bitbucket repository (no github) to the course’s submission web page. Add username "lgbanuelos" as a collaborator in your Bitbucket repository. Add the name of the team members in a file to Git repository (e.g. text file or markdown file).