Week 4 - Rest APIs

Java Annotations

Introduction to REST

Spring Boot Setup

Writing Endpoints

Message Formats

Input Validation

Practice

Assignment

• Teachers

Back end Track

Week 4 Assignment

Task 1 - Notes API

Overview

In this assignment, you will design and build a small REST API for personal notes using Spring Boot. The idea is simple. The API allows a client to create notes, list notes, filter notes, view one note, replace a note, delete a note, and receive clear validation errors when the request body is invalid.

You will start by designing the API contract, applying what you learned about REST APIs. Then you will implement it with models, controllers, and DTOs. Validate it using Jakarta Bean Validation.

Project Setup

Create a new project with Spring Initializr: https://start.spring.io

Settings

• Name: NotesAPI
• Group: com.{yourGroupId/githubTag}
• Dependencies:
  • Spring Web
  • Lombok
  • Validation
  • SpringDoc OpenAPI
    • Read the description on what it does. This may also give you a shortcut for the bonus section of this assignment

Requirements

Design and implement an API based on below requirements.

• API_DESIGN.md  documents all required endpoints before implementation
• Notes can be created with POST /api/v1/notes
• Note IDs are generated by the server
• All notes can be listed with GET /api/v1/notes
• Notes can be filtered by tag
• Pinned notes can be filtered with pinned=true
• One note can be fetched by ID
• A note can be fully replaced with PUT
• A note can be deleted with DELETE
• Models are kept separate from DTOs
• Error handling
• Correct HTTP status responses for all the above

Scoring Criteria

• Design:
  • Does it follow the REST principles?
  • Does it account for separation of concerns?
  • How easy is it to expand the API from the submitted result?
• Folder/Package structure:
  • How easy is it to expand the project with new features?
  • How easy is it to tell where does a new file belong?
• Endpoints:
  • Do endpoints cover all the requirements above?
  • Do they follow the REST principles? In-line with the design.
• Error handling:
  • How many errors are covered with how much code?
• Validation coverage:
  • Does it cover all validation scenarios that would be problematic for a database behind the API?
  • Does it have validation against application-layer DDoS attacks?

Bonus

Refactor your API to be using OpenAPI spec:

• Write the OpenAPI spec file for your API.

  • Named NotesAPI_v1-supplied.yaml , placed under src/main/resources

• Move all your validation to the spec file.

• Add the openapi-generator-maven-plugin

  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  

  • Read the docs or examples on how to set it up so that: When you execute mvn compile , your DTOs and API interfaces are generated and can be imported.
  • Add the <interfaceOnly>true</interfaceOnly> so that only an interface for your controllers are generated.

• Adjust controller to extend the Api interface instead.

• Remove your DTOs and use the generated ones instead.

<aside> 💭

For designing the API, you can either do so using markdown or OpenAPI specification. Depending on your choice, please create the file as follows:

• OpenAPI Spec: Create the file NotesAPI_v1-supplied.yaml under src/main/resources/specs
• Markdown: Create an API_DESIGN.md file in the project root.

You can also do the design in Markdown then move to OpenAPI spec.

</aside>

Submission

Follow the Assignment submission guide to learn how to submit the assignment

The HackYourFuture curriculum is licensed under CC BY-NC-SA 4.0 *https://hackyourfuture.net/*

Built with ❤️ by the HackYourFuture community · Thank you, contributors

Found a mistake or have a suggestion? Let us know in the feedback form.