Use Swagger Editor to design and document a REST API that provides all the actions needed in the scenario described above. For each endpoint, you must provide two responses: success (2xx) and error (4xx).

CO2103 HW3: REST API 

This coursework contributes 30% towards your CO2103 Semester 2 marks, i.e., 15% towards your final CO2103 module marks. 

Questions and Answers about this assignment must be posted on the Questions and Answers MS Teams channel.

Changelog 

• v1.2 (25-02-2021) 
  • Clarification added on the relationship between convenors and modules: a module is taught by one or multiple convenors. 
  • Clarification added on what happens when a convenor is deleted: their modules should also be deleted, except those that are taught by other convenors. 
  • Clarification added on endpoints #19-20; two filters should be available and should work either independently or together. 
• v1.1 (18-02-2021) 
  • Replace Integer with Long in SessionRepository:7 and ConvenorRepository:7. 
  • Remove Spring Security dependencies from build.gradle: 
    implementation `org.springframework.boot:spring-boot-starter-security` 
    testImplementation `org.springframework.security:spring-security-test` 
• v1.0 (18-02-2021) 
  • Worksheet Released. 

Plagiarism and Collusion 

This is an individual piece of coursework. Do not work with any other peers to avoid plagiarism or collusion concerns. 

Plagiarism and/or collusion will result in penalties that might go beyond this assignment: 
https://www2.le.ac.uk/offices/sas2/assessments/plagiarism/penalties 

Late Submission and Mitigating Circumstances 

Late submission penalties will be applied. Read the sections on late submission of coursework in your student handbook or here: https://www2.le.ac.uk/offices/sas2/assessments/late-submission. 

Accepted mitigating circumstances are the only means to have late submission penalties waived: https://www2.le.ac.uk/offices/sas2/regulations/mitigating-circumstances. 

Submission Instructions 

SUBMISSION LINK

Marking will be done anonymously with the help of automated scripts; do not include your username or name anywhere in your submission. 

Your submission must consist of a single zip file adhering to the following rules: 

• The file name must be hw3.zip. To package your project from STS:  
  • Right click on the project and select Refresh (to avoid warnings in the next steps)  
  • Right click on the project and select Export ... > Archive File 
  • Make sure project hw3 is selected on the top left  
  • Deselect the subfolders .gradle and build (if they exist, as usual and done for all lab submissions)  
  • Choose the name of the archive file to be hw3.zip (in a folder you like) and click Finish 
  • Upload your exported zip file to Blackboard Assessment and Feedback > HW3: REST API. You may try it as many times as you like before the deadline. Only the last submission attempt will be marked. 
  • Finally, download your submission from Blackboard, start a fresh workspace in STS and import your project from the file you have downloaded from Blackboard, and check that everything works.  
  • If your file is named differently or project is not exported following these steps, you will receive 0 marks. 
• Code must compile and execute without modifications. Your project must compile and execute directly with ./gradlew bootRun. If not, you will receive 0 marks. 
• Naming requirements set in each task must be obeyed (e.g., for files, Java classes, fields, packages, etc.). If you do not follow instructions precisely, you will receive 0 marks. 
• You must write your own solution. If you reuse any artifact from any of the worksheets or labs, your work is treated as plagiarism and receives 0 marks. 

Tasks 

The School of Informatics has hired you to develop a system to organise and manage modules` timetables. They are interested in keeping track of convenors, the modules they teach, and the sessions delivered in each module. The data they are interested in keeping track of is as follows: 

• Convenors 
  • long id: unique identifier for a convenor 
  • String name: the lecturer`s name e.g., "Jose Rojas" 
  • Position position: either "GTA", "Lecturer" or "Professor" (Position is an enum) 
• Modules 
  • String code: the module`s code and unique identifier, e.g., "CO2103", "CO3095" 
  • String title: the module`s title, e.g., "Software Architecture", "Calculus I" 
  • int level : the year in which the module is taught (a value between 1 and 4 representing Year 1–4) 
  • boolean optional: indicates whether the module is optional (i.e., true) or mandatory (false). 
• Sessions 
  • long id: unique identifier for a session 
  • String topic: the topic to be covered in the session, e.g., "RESTful APIs" 
  • Timestamp datetime: indicates the date and time when the session is taking place 
  • int duration: the duration of the session in minutes 

Besides the internal data needed for each resource as described above, there are evident relationships between these resources: 

• A module is taught by one or multiple convenors 
• A convenor can teach many modules 
• A module can have many sessions 
• A session belongs to one module 
• Deleting a convenor should delete all the modules they teach, except the modules that are also taught by another convenor, which should not be deleted 
• Deleting a module should delete all the sessions in the module but not the convenor 
• Deleting a session should not have any effect in modules or convenors 

The API you design and implement should provide the following endpoints: 

• Rest controller named edu.leicester.co2103.controller.ConvenorRestController with request mapping /convenors 
  • List all convenors (i.e., GET /convenors) (endpoint #1) 
  • Create (POST), retrieve (GET), update (only PUT) and delete (DELETE) a specific convenor (endpoints #2-5) 
  • List all modules taught by a convenor: /convenors/{id}/modules (endpoint #6) 
• Rest controller named edu.leicester.co2103.controller.ModuleRestController with request mapping /modules 
  • List all modules (endpoint #7)  
  • Create (POST), retrieve (GET), update (only PATCH) and delete (DELETE) a module (endpoints #8-11) 
  • GET /modules/{code}/sessions: list all sessions in a module (endpoint #12) 
  • Create (POST), retrieve (GET), update (PUT and PATCH) and delete (DELETE) a session in a module (e.g., POST /modules/{code}/sessions and GET /modules/{code}/sessions/{id}) (endpoints #13-17) 
• Rest controller named edu.leicester.co2103.controller.SessionRestController with request mapping /sessions  
  • Delete all sessions (DELETE /sessions)(endpoint #18) 
  • List all sessions, allowing filtering by convenor (convenor ID) and by module (module code), e.g., /sessions?convenor=1&module=co2103, /sessions?convenor=1 or /sessions?module=co2103. It should be possible to use only one filter or both together. (endpoints #19-20) 

Task 1. Design and Documentation [40 marks, 2 marks for each endpoint] 

Use Swagger Editor to design and document a REST API that provides all the actions needed in the scenario described above. For each endpoint, you must provide two responses: success (2xx) and error (4xx).  

Make sure you are using Open API 3 (OAS3). This will be obvious if the first line in your file is openapi: 3.0.1. If it is not, you have to click on Edit > Convert to OpenAPI 3 > Convert. 

The Swagger Editor at http://editor.swagger.io/ is free to use. You can clear the editor and start from scratch (File > Clear Editor), or take inspiration from the Petstore API that loads up when you first visit the website. To work effectively and avoid losing your work, you will have to save your work to your local computer frequently with File > Save as YAML and load it to continue working on it with File > Import file. 

For inspiration on how to describe the content of each of your resources (the content of your resources / JSON objects), you can read this article: https://swagger.io/docs/specification/describing-request-body/ 

Submission 

You must provide an Open API 3 spec in YAML format for this task. The name of the file must be hw3.yaml. To produce this file on Swagger Editor you will click on File > Save as YAML. Do not forget to rename your downloaded JSON spec to hw3.yaml. Finally, place the file in the src/main/resources/ directory of the Spring project you will create in Task 2. The project template will contain a file with the following content: 

openapi: 3.0.1 
 
info: 
  title: HW3 
 
# Placeholder file, replace it with your Open API 3 spec 

 

Task 2. Implementation [40 marks, 2 marks for each endpoint] 

Use the attached hw3.zip archive file as a starting project. It contains the basic implementation of domain and repository classes and the creation of some test data in the Hw3Application class: 

@Override 
public void run(ApplicationArguments args) throws Exception { 
   Session s1 = new Session(); 
   s1.setDatetime(Timestamp.valueOf("2021-02-24 12:00:00")); 
   s1.setDuration(2); 
   s1.setTopic("REST APIs"); 
   s1 = sessionRepo.save(s1); 
 
   Module m1 = new Module("CO2103", "Software Architecture", 2, false); 
   m1.getSessions().add(s1); 
   m1 = moduleRepo.save(m1); 
 
   Session s2 = new Session(); 
   s2.setDatetime(Timestamp.valueOf("2021-02-26 14:00:00")); 
   s2.setDuration(2); 
   s2.setTopic("Unit Testing"); 
   s2 = sessionRepo.save(s2); 
 
   Module m2 = new Module("CO3095", "Software Quality", 3, true); 
   m2.getSessions().add(s2); 
   m2 = moduleRepo.save(m2); 
 
   Convenor c1 = new Convenor("Jan Ringert", Position.PROFESSOR); 
   c1.getModules().add(m1); 
   c1 = convenorRepo.save(c1); 
 
   Convenor c2 = new Convenor("Jose Rojas", Position.LECTURER); 
   c2.getModules().add(m1); 
   c2.getModules().add(m2); 
   c2 = convenorRepo.save(c2); 
} 

Load the project on Spring Tool Suite and use it to and implement the REST API you have designed in Task 1. You can follow a similar approach to the one you followed in Lab 6. 

Your task is to implement all the endpoints described in the previous section in the appropriate rest controllers: ConvenorRestController, ModuleRestController and SessionRestController. These files already exist in the project, but you have to write the necessary code to handle all the required REST requests. 

Once you are done, make sure your project runs and deploys on http://localhost:8080 when you run: 

./gradlew bootRun 

This is very important. If your project does not execute without errors, this task will not be marked. 

Task 3. Testing [20 marks, 1 for each tested endpoint] 

In this task, you will use Postman to create two test requests for each of your endpoints: one for a successful response and one for an error response. Create a Postman Collection and make sure all the tests run correctly in sequence. 

Submission 

Export your Postman Collection as a JSON file by clicking on Export > Collection v2.1 (recommended). This will prompt you to save the file hw3.postman_collection.json which you will place in your project from Task 2 src/main/resources/hw3.postman_collection.json. Your template project contains a placeholder file: 

{ 
  "info": "Placeholder file, replace it with your Postman Collection" 
} 

 

Assessment 

Exceptional (up to 100) 

• All the required endpoints have been correctly documented in the spec 
• All the required endpoints have been implemented and run as expected, matching perfectly with the documentation 
• The Postman collection contains one successful and one error test case for each endpoint and all tests execute correctly 

Outstanding (80s) 

• Most endpoints have been correctly documented in the spec 
• Most endpoints have been implemented and run as expected, matching perfectly with the documentation 
• The Postman collection contains one successful and one error test case for most of the endpoints 

Excellent (70s) 

• Most endpoints have been documented in the spec, although there are some gaps with respect to the requirements, e.g., the relationships between entities are not implemented 
• Most endpoints have been implemented and run as expected, although the matching with the documentation is not perfect, e.g., the documentation includes an endpoint that is not implemented 
• The Postman collection contains one successful and one error test case for most of the endpoints, but some of them are problematic and do not execute correctly 

Competent (60s) 

• At least 2/3 of the endpoints have been documented in the spec, with noticeable gaps with respect to the requirements 
• At least 2/3 of the endpoints have been implemented and run as expected, although the matching with the documentation is not perfect 
• The Postman collection contains one successful and one error test case for each of the implemented endpoints, but several of them are problematic and do not execute correctly 

Satisfactory (50s) 

• At least half of the endpoints have been documented in the spec, with noticeable gaps with respect to the requirements 
• At least half of the endpoints have been implemented and run as expected, although the matching with the documentation is not perfect 
• The Postman collection contains one successful and one error test case for each of the implemented endpoints, but several of them are problematic (e.g., incorrect responses or missing behaviour) and do not execute correctly 

Adequate (40s) 

• Less than half of the endpoints have been documented in the spec, with noticeable gaps with respect to the requirements, e.g., most relationships between entities have not been implemented 
• Less than half of the endpoints have been implemented and run as expected with a noticeable mismatch with the documentation 
• The Postman collection contains one successful and one error test case for each of the implemented endpoints, but several of them are problematic; few of them execute without errors 

Marginal (to 35) 

• Up to 1/3 of the endpoints have been documented in the spec, with noticeable gaps with respect to the requirements 
• Up to 1/3 of the endpoints have been implemented and run as expected, with a noticeable mismatch with the documentation 
• The Postman collection contains one successful and one error test case for each of the implemented endpoints, but several of them are problematic; few of them execute without errors 

Little effort (to 20) 

• The Open API 3 documentation does not reflect the requirements correctly 
• The implementation is severely flawed, with multiple noticeable errors 
• The Postman collection only includes trivial tests without relevance to the requirements 

Non-adherence (10s) 

• The Open API 3 JSON file is missing or is not a valid spec 
• The implementation is missing or does not compile 
• The Postman collection YaAML file is missing or the file is invalid 

Nominal (below 10) 

• No meaningful work is observed in the submission.