The aim of this coursework is to practice the Enterprise Middleware development principles covered in the lectures and practical classes.
Before attempting this coursework you should revisit this tutorial. As OpenShift will not be used in this assessment, all OpenShift related instructions can be ignored.
In this assessment, you are required to develop a RESTful web service built using Quarkus to provide users the ability to leave reviews of restaurants. In particular, you will use the following technologies:
-
Quarkus. A full-stack Java framework used to build highly scalable enterprise applications.
-
JPA. The Java Persistence API provides a Java API onto your application’s data.
-
JTA. The Java Transaction API is a general API for managing transactions in Java. It allows you to start, commit and rollback transactions in a resource neutral way.
-
JSON. This is the data serialization and interchange format used by Javascript and commonly returned by HTTP APIs.
-
Bean Validation. This technology allows you to specify constraints on your data and assists with validation.
-
JUnit and REST Assured. These tools will be used to test your REST endpoints.
-
Maven. Your application will be built and deployed with this tool.
-
JAX-RS. This technology provides the API for developing REST services. You will use this technology to communicate between distributed components of your application (web-interfaces & other services).
-
Git. This is a distributed version control system and will be used to backup your code.
-
Swagger. Swagger is a simple yet powerful representation of your RESTful API. Using Java @Annotations Swagger will generate documentation for JAX-RS endpoints as part of the project build process.
This coursework is split into two parts.
In Part One of the coursework, you will build a simple web service which exposes three RESTful resources which are User, Restaurant and Review. Using this API, a user should be able to create user accounts and restaurants. A user should also be able to submit a review for a restaurant, which contains the review information along with the associated user and restaurant data.
In Part Two of the coursework, you will provide functionality that allows a user to delete their account from the restaurant review service. This functionality should not only remove the user account from the database but also remove all associated reviews for that user. It is very important that you achieve this using the Java Persistance API as explained below.
The Assessment Criteria section describes the expected functionality from your web service in finer detail. You should strive to meet all requirements within this criteria and regularly refer back to this section as you work on your project.
Building your work
For this project you must use a Maven build for your application. You may use the Maven build file (pom.xml) provided as part of the tutorial.
Storing your work
You should save your work using the Git version control system, regularly committing changes and pushing to the provided GitHub repository.
You should push commits of your coursework regularly to your GitHub repo. It is a good idea to do so every time you get a small piece of functionality working. This ensures that you can move back to a working state if you get in a mess. It also ensures that you have a backup and that the demonstrators can view your code and track progress.
|
Tip
|
You will be awarded a considerable number of marks for your distribution and use of version control. We expect to see a steady flow of sensible commits to Github over the coursework period. |
Testing your work
You must produce REST Assured tests for testing your application. These tests will be executed as part of your Maven build.
You should build on the contacts-swagger example from the tutorial. You do not have time to create a new application from scratch. Don’t worry about renaming the packages, doing so is likely to get you into a mess.
Produce an API offering users the ability to create user accounts, restaurants and reviews. Your API must conform to RESTful design principles and should return JSON. Finally you must construct REST Assured tests to demonstrate that your service satisfies the requirements below.
-
Unit Tests. These are implemented using the REST Assured testing framework and send requests to your REST services, validating the responses against some expected response.
-
REST Services. These are implemented using RESTEasy (a JBoss implementation of the JAX-RS Java Standards Recommendation (JSR)) and provide a service interface to your application. These services are responsible for managing users, restaurants and reviews.
-
Persistence layer. This layer provides a Java interface for accessing the data in the database, using the Java Persistence API (JPA).
-
Database. This is where your data is stored. Your application won’t access this directly as it will use JPA to interface with the data.
You will need to produce three RESTful resources:
-
User
-
Restaurant
-
Review
Your API should provide endpoints to perform the following actions on your resources:
-
Create & List Users.
-
Create & List Restaurants.
-
Create & List Reviews.
You must document your endpoints using Swagger @Annotations, including:
-
Their purpose.
-
Their expected URL structure & request method.
-
Their expected request values.
-
Their expected response format.
-
Possible HTTP response codes and the reasons for them.
|
Tip
|
Much of the information about each REST endpoint, such as URL structure and request method, may be automatically discovered by Swagger. All Swagger @Annotations should be included in the relevant *RestService class.
|
You will need an Entity for each of your resources.
-
User. A bean to hold the data you wish to collect about each user.
-
Restaurant. A bean to hold the data you wish to collect about each restaurant.
-
Review. A bean to hold the review information along with the associated user and restaurant for the review.
|
Tip
|
Keep these entities simple. Just provide the minimum information required to fulfil the requirements of the assessment criteria below. Use @Annotations, like those found in the base contacts-swagger Contact class, to specify validation constraints on your information (like the minimum length of a name).
|
|
Tip
|
When you are testing your application you may find it useful to pre-populate your database with a number of example entities. One way to achieve this is to add SQL insert statements into src/main/resources/import.sql.
|
|
Tip
|
When you are testing your application you will find it useful to view the queries run against your database. You can enable logging of this information by setting the hibernate.show_sql property to true in src/main/resources/META-INF/persistence.xml.
|
After completing Part One, the final step is to provide the functionality to allow users to delete their accounts. This functionality should be provided by creating a new endpoint on the User resource. When a user deletes their account, it is important that all reviews created by the user should be removed from the database.
This functionality can be automated through the use of the JPA Entity relationship @Annotations (e.g. @ManyToOne, @ManyToMany etc…), which are provided by Hibernate. You should therefore implement all relationships between entities using these annotations, even if you did not do so in Part One.
|
Tip
|
This will mean that you should store full objects (or lists of objects) in your models, rather than just ID’s. You should be careful to familiarise yourself with the Jackson JSON annotations if you have not done so already (particularly @JsonIgnore which prevents the "recursive" definition problem).
|
-
Be able to create a User record with a name, an email and a phone number.
-
Be able to retrieve a collection of all users with a single request.
-
Be able to create a Restaurant record with a name, phone number and postcode.
-
Be able to retrieve a collection of all restaurants with a single request.
-
Be able to create a Review record, with a User ID, a Restaurant ID, the review text and rating out of 5.
-
Be able to retrieve a collection of all reviews made by a particular User, with a single request.
-
Be able to delete a User.
-
Not be able to create a User/Restaurant/Review record with incomplete or invalid information.
The following validation requirements must be provided:
-
User name: a non-empty alphabetical string less than 50 characters in length.
-
User email: a non-empty string which is a valid email address.
-
User phone number : a non-empty string which starts with a 0, contains only digits and is 11 characters in length.
-
Restaurant name: a non-empty alphabetical string less than 50 characters in length.
-
Restaurant phone number: a non-empty string which starts with a 0, contains only digits and is 11 characters in length.
-
Restaurant postcode: a non-empty alpha-numerical string which is 6 characters in length.
-
Review review: a non-empty string less than 300 characters in length.
-
Review rating: a numerical value with a minimum value of 0 and a maximium value of 5.
-
User/Restaurant/Review id: a Long, which should not be settable or changable by an API consumer.
The following are the variables, or sets of variables, which should be unique for each Object of each Entity type in your system:
-
User email: A user’s email address should be unique to that customer.
-
Restaurant phone number: A restaurants phone number should be unique to that restaurant.
-
Review User & Restaurant: A User should only be able to leave a review for a restaurant once.
Prior to submission you will provide a 10-15 minute demonstration to one of the Course Demonstrators. You will be expected to describe your technical solution and discuss your personal experiences throughout the project.
In addition to the above, you will also be asked a series of questions based on the material presented throughout the module and questions relating to the technologies you have used to complete the coursework. This viva is mandatory for the resit assessment. Once you have completed the coursework, please email [email protected] to organise a time to demonstrate your coursework,
You must submit all work via the coursework submission system (NESS). This should constitute a zip file containing the project source code and Maven build scripts. We will use this zip file to test your submission, so it should contain everything necessary to build and test your project.
You may ask questions about anything that is not clear in the document. To do so, please email [email protected]. Any questions encountered frequently during the module are available in a Frequently Asked Questions document which we maintain here. Before asking a question we encourage you to check this link to see if it has already been answered.