Workshop #3: Enhancing API layer

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

Let's take a sample GET request:

https://api.example.com:3000/shop/v1/items?category=fruits

and decompose it into the parts:

http:// - request protocol (http or https)
api.example.com - host
3000 - port (for http default port is 80 and for https is 443)
/shop/v1/items - request URI
?category=fruits - query params

Additionally, an HTTP request can contain:

request body (it can be in plain text, x-www-form-urlencoded, binary, JSON, etc.)
request headers

HTTP response structure

Each HTTP response contains:

response headers
response body
HTTP status code

REST API

What is REST API

According to Red Hat, REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. REST stands for representational state transfer and was created by computer scientist Roy Fielding.

An API is a set of definitions and protocols for building and integrating application software. It’s sometimes referred to as a contract between an information provider and an information consumer.

How to build a 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

Now let's dig into code and see how we can write readable and easily extensible REST APIs in Spring Boot.