Skip to content

Workshop #3: Enhancing API layer

Jump to bottom
Marcin Zielonka edited this page Nov 22, 2022 · 24 revisions

About 📝

Workshop #3 is about enhancing the API layer - not only the REST one but the API contract in general (e.g. between modules communicating with each other). Therefore, you can find topics such as:

  • HTTP basics (methods, status codes, etc.)
  • REST API conventions
  • Swagger definitions
  • Java components visibility
  • SOLID

This workshop

Source code 🗃

You can find the source code that represents the status of the project after this workshop - TBD

HTTP basics

Let's recollect what the HTTP is and what is the proper way to use it in terms of building efficient and readable REST APIs :)

What is HTTP

HTTP stands for Hyper Text Transfer Protocol. This protocol is used to transfer data (HTML documents, CSS/JS files, JSON data, etc.) over the Internet between clients and servers via HTTP requests and HTTP responses.

HTTP methods

We can distinguish 5 mostly used HTTP methods: GET, POST, PUT, DELETE, PATCH (full list available on https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods site).

HTTP Method Description Safe Idempotent Has request body Has response body
GET Read a resource Yes Yes Optional Yes
POST Create a new resource No No Yes Yes
PUT Update a resource No Yes Yes Yes
DELETE Delete a resource No Yes Optional Optional
PATCH Update partially a resource No No Yes Yes

HTTP status codes

HTTP response status codes indicate the result of the processed HTTP request. They are grouped into five classes:

  • 1xx: Informational responses
  • 2xx: Successful responses
  • 3xx: Redirection responses
  • 4xx: Client error responses
  • 5xx: Server error responses

A full list of HTTP status codes can be found on https://developer.mozilla.org/en-US/docs/Web/HTTP/Status site.

HTTP request structure

HTTP response structure

REST API

What is REST API

How to build good REST API

Use HTTP methods to describe an action

Endpoint to describe a resource

Use kebab-case for endpoint naming

Return proper status codes

Query params for filtering

Support pagination

Versioning

Standardized error responses

Swagger

What is Swagger

What is OpenAPI

Building efficient REST API layer with Spring Boot

Use DTOs for both request body and responses

Delegate all business logic to the service layer

Handle errors

Apply Swagger

Building scalable domain-driven application

Group code by domain

Apply proper component visibility

One responsibility per component

Clone this wiki locally