REST

REST stands for Representational State Transfer. It is an architectural style used for designing networked applications, especially web services. REST is a set of rules that define how clients (like browsers or apps) and servers communicate over the web. It’s commonly used when building APIs (like in Spring Boot) so that different systems can talk to each other using HTTP. REST is built on top of HTTP, and uses a request and response pattern.

+--------+                                +--------+
| Client |                                | Server |
+--------+                                +--------+
     |                                        ^
     |  HTTP Request (GET, POST, etc.)        |
     |--------------------------------------->|
     |                                        |
     |          HTTP Response (JSON, HTML)    |
     |<---------------------------------------|
     v                                        |

Key features

Concept	Explanation
Resource	Any object or data (like a user, post, product) that can be accessed. Each has a URL. Example: /users/123 is a resource for user with ID 123.
Representation	How the resource is formatted. REST typically uses JSON or XML to represent the resource.
Stateless	Each request from the client must contain all the information needed; the server does not store anything about the client between requests.
Standard HTTP methods	REST uses the standard HTTP verbs to perform actions on resources

REST API conventions

Use pluralised nouns for resources

Use plural version of the noun to name your resource URL.

One book (using ID of that book):
/books/9789021

The collection of books:
/books

HTTP verbs

You can have the same URL but different HTTP verbs to execute different actions. For example GET /users/123 retrieves the user 123, POST /users/123 creates a new user 123.

HTTP Verb	Action	Description	Example	Request body
GET	Read	Retrieves a representation of a resource without modifying it.	GET /users/123 → Get user 123	None
POST	Create	Creates a new resource on the server.	POST /users → Create new user	Full represetnation
PUT	Update/Replace	Replaces a resource entirely. You should provide the full representation of the resource in the request body.	PUT /users/123 → Replace user 123	Full represetnation
PATCH	Update/Modify	Partially updates a resource. You don’t provide the full representation of the resource in the request body.	PATCH /users/123 → Update name only	Partial represetnation
DELETE	Delete	Removes the resource.	DELETE /users/123 → Delete user 123	None

HTTP response code in REST

HTTP response codes are standard 3-digit status codes sent by the server to indicate the outcome of an HTTP request. RESTful APIs use these codes to clearly communicate whether a request was successful, failed, or had some other outcome.

Code Range	Meaning	Usage in REST APIs
1xx	Informational	Rarely used in REST
2xx	Success	The request succeeded
3xx	Redirection	Usually avoided in REST unless for location redirects
4xx	Client error	Something wrong with the request
5xx	Server error	Server failed to process a valid request

Common HTTP codes in REST

Success codes (2xx)

Code	Meaning	REST Use Case
200 OK	Request succeeded	Standard response for GET, PUT, or DELETE
201 Created	Resource created	Response to successful POST
204 No Content	Success, no response body	Used for DELETE or successful update with no body

Client error code (4xx)

Code	Meaning	REST Use Case
400 Bad Request	Invalid request data	Missing fields, wrong format, etc.
401 Unauthorized	Not authenticated	Client must log in (e.g., missing token)
403 Forbidden	Authenticated but no permission	Access denied to the resource
404 Not Found	Resource doesn’t exist	Wrong URL or ID
409 Conflict	Resource conflict	e.g., duplicate entry on POST
422 Unprocessable Entity	Semantically invalid data	e.g., failed validation

Server error code (5xx)

Code	Meaning	REST Use Case
500 Internal Server Error	Generic server error	Unexpected failure during processing
503 Service Unavailable	Server is down or overloaded	Temporary maintenance or overload

Query parameter and URL path

Query parameter

Use query parameters when you need additional information in your request, but it doesn’t make sense to put it in the URL path. It is a key-value pair appended to the end of URL to send additional data. Often used for filtering, searching, sorting, or paginating.

Basic syntax: Query parameters are added after a ? in the URL. Multiple parameters are separated by &.

https://example.com/resource?key1=value1&key2=value2

Examples in a REST API

Example 1: Filtering Fetch all users with the role “admin”.

GET /users?role=admin

Example 2: Searching Search for products with “pepsi” in the name or description

GET /products?search=pepsi

Example 3: Pagination

GET /posts?page=2&limit=10

---

Back to parent page: Spring and Spring Boot