5COSC022W JAX-RS REST API Assignment: Airline Agency System for Flight, Passenger & Booking Management

This assignment contributes towards the following Learning Outcomes (LOs):

• LO1 Gain a thorough understanding of RESTful principles and their application in API design.
• LO2 Acquire familiarity with the JAX-RS framework as a tool for building RESTful APIs in Java.

Key Dates

Handed Out: February 2025

Due Date: 30th June 2025, 13:00

Expected deliverables

• A zip file containing the developed project
• Video demonstration
• Report in a pdf format

Method of Submission:

Electronic submission on Blackboard via a provided link close to the submission time.

Type of Feedback and Due Date:

Written feedback within 15 working days.

BCS CRITERIA MEETING IN THIS ASSIGNMENT

• 2.1.1 Knowledge and understanding of facts, concepts, principles & theories
• 2.1.2 Use of such knowledge in modelling and design
• 2.1.3 Problem solving strategies
• 2.2.1 Specify, design or construct computer-based systems
• 2.2.4 Deploy tools effectively
• 2.3.2 Development of general transferable skills
• 3.1.1 Deploy systems to meet business goals
• 4.1.1 Knowledge and understanding of scientific and engineering principles
• 4.1.3 Knowledge and understanding of computational modelling

Assessment regulations

Refer to section 4 of the “How you study” guide for undergraduate students for a clarification of how you are assessed, penalties and late submissions, what constitutes plagiarism etc.

Penalty for Late Submission

If you submit your coursework late but within 24 hours or one working day of the specified deadline, 10 marks will be deducted from the final mark, as a penalty for late submission, except for work which obtains a mark in the range 40 – 49%, in which case the mark will be capped at the pass mark (40%). If you submit your coursework more than 24 hours or more than one working day after the specified deadline you will be given a mark of zero for the work in question unless a claim of Mitigating Circumstances has been submitted and accepted as valid.

It is recognised that on occasion, illness or a personal crisis can mean that you fail to submit a piece of work on time. In such cases you must inform the Campus Office in writing on a mitigating circumstances form, giving the reason for your late or non-submission. You must provide relevant documentary evidence with the form. This information will be reported to the relevant Assessment Board that will decide whether the mark of zero shall stand. For more detailed information regarding University Assessment Regulations, please refer to the following website: http://www.westminster.ac.uk/study/current-students/resources/academic-regulations

Learning Goals:

• Define key principles of REST architecture.
• Differentiate between RESTful and non-RESTful APIs.
• Recognize the importance of resource-based interactions.
• Understand the role of JAX-RS in Java-based API development.
• Explore JAX-RS annotations for resource mapping and HTTP method handling.
• Implement basic resource classes using JAX-RS.

Introduction

This coursework is designed to provide you with practical experience in designing and implementing RESTful web services using the Java API for RESTful Web Services (JAX-RS). You will build a comprehensive “Airline Agency” application API, gaining hands-on experience with core RESTful principles, JAX-RS features, and common API design patterns.

This project simulates a real-world scenario where you need to create a robust and scalable backend API to manage various entities like flights, passengers and Bookings. You’ll learn how to structure your application using resource classes, handle different HTTP methods, process requests and responses, and implement proper error handling.

Coursework Objectives

Upon successful completion of this coursework, you will be able to:

• Understand and apply the fundamental principles of RESTful architecture.
• Design and implement RESTful APIs using the JAX-RS specification.
• Structure a JAX-RS application using resource classes and sub-resources.
• Handle various HTTP methods (GET, POST, PUT, DELETE) appropriately.
• Work with different data formats, specifically JSON, for request and response bodies.
• Implement data validation and exception handling using ExceptionMapper.
• Understand and implement basic API testing using Postman.
• Model basic e-commerce functionalities such as shopping cart and order management.

Coursework Specifications

Application Domain:

In this coursework, you will develop a RESTful service for an Airline Agency. This coursework will focus on understanding and applying core JAX-RS annotations, concepts for resource management using in-memory data structures, robust error handling with custom exceptions and ExceptionMappers, and logging practices.

1. Core Entities

• Flight:

• flightNumber (String – e.g., “BA2490”)
• origin (String – e.g., “London”)
• destination (String – e.g., “New York”)
• departureTime (String – e.g., “2025-12-25T10:30:00Z”)
• arrivalTime (String – e.g., “2025-12-25T13:30:00Z”)
• capacity (int)
• availableSeats (int)

• Passenger:

• passengerId (String – auto-generated or simple counter) – Primary Key
• firstName (String)
• lastName (String)
• email (String)

• Booking:

• bookingId (String – auto-generated or simple counter) – Primary Key
• flightNumber (String – links to a Flight)
• passengerId (String – links to a Passenger)
• bookingDate (String – e.g., “2025-10-01T15:00:00Z”)
• seatNumber (String – e.g., “12A”, optional or auto-assigned)

2. Data Storage

• Use java.util.HashMap to store collections of Flights, Passengers, and Bookings. The primary key of each entity should be the key in the HashMap.
• For example: HashMap<String, Flight> flights = new HashMap<>();
• You might also use java.util.ArrayList

3. Custom Exceptions

Define and use the following custom exceptions (or similar ones that fit your design) to handle specific error conditions. These should extend RuntimeException or a common application-specific base exception.

• ResourceNotFoundException: For scenarios where a specific resource (Flight, Passenger, Booking) is not found.

• Example: FlightNotFoundException extends ResourceNotFoundException
• Example: PassengerNotFoundException extends ResourceNotFoundException
• Example: BookingNotFoundException extends ResourceNotFoundException

• BadRequestException (or InvalidRequestException): For invalid input data or requests that cannot be processed.

• Example: FlightAlreadyExistsException extends BadRequestException (for creating a flight with a duplicate ID)
• Example: NoAvailableSeatsException extends BadRequestException (when trying to book a full flight)
• Example: InvalidFlightCapacityException extends BadRequestException (if capacity is set to a non-positive number)

4. ExceptionMappers

Implement JAX-RS ExceptionMapper classes for your custom exceptions to translate them into standardized HTTP responses.

• ResourceNotFoundExceptionMapper:

• Maps any ResourceNotFoundException (and its subclasses) to a 404 Not Found HTTP response.
• The response body should be a JSON object like: {“errorCode”: “RESOURCE_NOT_FOUND”, “message”: “The requested resource was not found.”} (or the specific message from the exception).

• BadRequestExceptionMapper:

• Maps any BadRequestException (and its subclasses) to a 400 Bad Request HTTP response.
• The response body should be a JSON object like: {“errorCode”: “INVALID_REQUEST”, “message”: “The request is invalid or cannot be processed.”} (or the specific message from the exception).

• (Optional) GenericExceptionMapper:

• Maps Throwable or RuntimeException to a 500 Internal Server Error HTTP response.
• Response body: {“errorCode”: “INTERNAL_SERVER_ERROR”, “message”: “An unexpected error occurred.”}
• Ensure this mapper has a lower priority if multiple mappers could handle an exception, or make it specific to unhandled RuntimeExceptions.

5. Logging

Integrate logging using SLF4J or Log4J Configuration:

• Configure the logger (e.g., logback.xml in src/main/resources) to output logs to the console and/or a file. Define log levels (INFO, DEBUG, WARN, ERROR).
• Log key events:
  • Entry and exit of public API methods (DEBUG or INFO level).
  • Successful creation/update/deletion of resources (INFO level).
  • Resource not found occurrences (WARN level, before throwing the exception).
  • Bad requests (WARN level, before throwing the exception).
  • Caught exceptions in ExceptionMappers (ERROR level, especially for the generic mapper).
  • Important business logic steps (e.g., “Decrementing available seats for flight X”, “Flight Y has no available seats” – INFO or DEBUG).
  • Application startup and shutdown events if applicable (INFO level).

6. API Endpoints (CRUD Operations)

6.1. Flight Endpoints

• POST /flights: Create a new flight.
  • Throws FlightAlreadyExistsException if flightNumber is not unique.
  • Throws InvalidFlightCapacityException if capacity <= 0.
  • Log request, success, or failure.
• GET /flights: Get all flights.
  • Log request and number of flights returned.
• GET /flights/{flightNumber}: Get a specific flight.
  • Throws FlightNotFoundException if not found.
  • Log request, success (with flight number), or failure.
• GET /flights/search: Search for flights.
  • Log request, criteria, and results.
• PUT /flights/{flightNumber}: Update an existing flight.
  • Throws FlightNotFoundException if not found.
  • Log request, update details, success, or failure.
• DELETE /flights/{flightNumber}: Delete a flight.
  • Throws FlightNotFoundException if not found.
  • Throws FlightHasBookingsException if you implement the constraint that flights with bookings cannot be deleted directly.
  • Log request, success, or failure.

6.2. Passenger Endpoints

• POST /passengers: Create a new passenger.
  • Log request, success, or failure.
• GET /passengers: Get all passengers.
  • Log request and number of passengers returned.
• GET /passengers/{passengerId}: Get a specific passenger.
  • Throws PassengerNotFoundException if not found.
  • Log request, success, or failure.
• PUT /passengers/{passengerId}: Update passenger details.
  • Throws PassengerNotFoundException if not found.
  • Log request, success, or failure.
• DELETE /passengers/{passengerId}: Delete a passenger.
  • Throws PassengerNotFoundException if not found.
  • (Consider if you want to throw an exception if the passenger has bookings).
  • Log request, success, or failure.

6.3. Booking Endpoints

• POST /bookings: Create a new booking.
  • Throws FlightNotFoundException or PassengerNotFoundException if related entities don’t exist.
  • Throws NoAvailableSeatsException if the flight is full.
  • Log request, involved flight/passenger, success, or failure.
  • Logic:
    • Verify flight and passenger exist (throw if not).
    • Check availableSeats (throw if none).
    • Decrement availableSeats.
• GET /bookings: Get all bookings.
  • Log request and number of bookings.
• GET /bookings/{bookingId}: Get a specific booking.
  • Throws BookingNotFoundException if not found.
  • Log request, success, or failure.
• GET /flights/{flightNumber}/bookings: Get bookings for a flight.
  • Throws FlightNotFoundException if flight doesn’t exist.
  • Log request and results.
• GET /passengers/{passengerId}/bookings: Get bookings for a passenger.
  • Throws PassengerNotFoundException if passenger doesn’t exist.
  • Log request and results.
• DELETE /bookings/{bookingId}: Cancel a booking.
  • Throws BookingNotFoundException if not found.
  • Log request, success, or failure.
  • Logic: Increment availableSeats for the corresponding flight.

7. Code Structure:

• Organize your code into the specified resource classes.
• Follow best practices for JAX-RS development.
• Use meaningful names for variables, methods, and classes.

7. Report Structure:

This report requires you to document the test cases you have designed and executed for your RESTful Airline Agency API. The report will consist primarily of tables that clearly outline each endpoint, its expected behavior, and the results of your tests.

Your report should have the following structure:

1. Introduction (Brief – Approximately 1/4 page)

• Briefly introduce the purpose of the report, which is to document the test cases for your Airline Agency API.
• Mention the technologies used to build the API (JAX-RS, JSON) and the tool used for testing (Postman).
• State that the report focuses on presenting test cases in a tabular format.

2. API Endpoint Test Case Tables (Main Content of the Report)

• For each endpoint in your API, create a separate table to document its test cases.
• Organise the table by resource class.
• Use the following table structure for each endpoint:

Sample Test Case Table: POST /flights Endpoint:

Important Reminders:

• Comprehensive Test Cases: Ensure that your test cases cover a wide range of scenarios for each endpoint, including valid inputs, invalid inputs, edge cases, and error conditions.
• Postman for Execution: You must use Postman to execute your test cases and record the results in the tables.
• Focus on Documentation: The primary goal of this report is to clearly document your test cases and their results.

Coursework Policies and Regulations

1. Technology Restrictions:

• This coursework strictly prohibits the use of any technologies other than JAX-RS, JSON, and Postman (and basic Java for data models and in-memory storage).
• No external databases, persistence frameworks (e.g., Hibernate), Spring, dependency injection frameworks, or external libraries are allowed.
• Using any prohibited technology like Spring or Flask or any Database technology like SQL will result in a mark of zero (0) for the entire coursework.
• You must only follow the concepts we covered during the tutorials. If you use any other irrelevant piece of code that is not related to the scenario or the required task, you will lose your mark for related parts/classes.

2. Code formatting and comments

• You must ensure that your codes are well-formatted and supported by detailed comments, especially for complex coding parts. Otherwise, your mark for any related class will be reduced.

3. Originality:

• All submitted code must be your own original work.
• Plagiarism or any form of academic misconduct will not be tolerated and will result in severe penalties.

4. Submission:

• You must submit a zip file containing your project code and the Postman collection.
• Detailed submission instructions will be provided separately.

5. Late Submissions:

Late submissions will be penalized according to the standard university policy [see http://www.westminster.ac.uk/study/current-students/resources/academic-regulations].

Video Demonstration Details

A significant portion of your grade will be based on a video demonstration of your API using Postman. Here’s what you need to do:

1. Postman Collection:

Create a Postman collection that includes requests for all the endpoints of your API.

2. Test Cases:

• Include a variety of test cases for each endpoint, covering both positive (successful) and negative (error) scenarios.
• For example, for the POST /flights endpoint, you should demonstrate creating a flight with valid data, as well as attempting to create a flight with missing fields, incorrect data types, or a non-existent flight number.
• Demonstrate the scenarios where your ExceptionMapper should be triggered and verify that the correct HTTP status codes and error messages are returned.

3. Recording:

• Record a video of yourself using Postman to send requests to your API and show the responses. The length of the video demonstration should not exceed 10 minutes.
• Your video should be clear, well-paced, and easy to follow.
• If you do not submit a video demonstration, your mark will be zero for the demo parts specified in the rubric.
• Explain each request as you send it, describing the purpose of the request, the expected outcome, and the actual outcome.
• Highlight the use of different HTTP methods (GET, POST, PUT, DELETE) and HTTP status codes in your demonstration.

Grading Rubric

A detailed grading rubric has been provided separately. It outlines the specific criteria for each aspect of the coursework, including:

• Correctness of code implementation for each resource class and endpoint
• Quality and completeness of the video demonstration
• Proper exception handling
• Overall code quality

Support and Clarifications

If you have any questions or need clarification on any aspect of the coursework, please do not hesitate to ask your instructor or teaching assistant during office hours or through the designated communication channels (e.g., forum, email).

Submission deadline and guidance:

1. Submission Format: All coursework must be submitted as a ZIP file containing your work. The ZIP file should be named in the following format: <student-id>_<student-name>_<module>. For example, if your student ID is “12345”, your name is “John Smith”, and the module is “CS101”, your ZIP file should be named as 12345_JohnSmith_CS101.zip.
2. Report Submission: Alongside the ZIP file, please submit a PDF report detailing your coursework. The report should also follow the naming convention mentioned above: <student-id>_<student-name>_<module>.pdf.
3. Deadline: The submission deadline is June 30, 2025, 13:00. Late submissions will not be accepted unless any special circumstance happens, e.g. you submit an MC form.
4. Submission Channel: You must submit your coursework through the Blackboard using the given link under assessments.
5. Contact: If you encounter any issues or have questions regarding the submission process, feel free to contact your course instructor for assistance.