REST Principles: Resources, HTTP Methods, Response Codes

Let's kick off with the REST API manifesto: resources are the alpha and omega — the whole point of REST. Remember how we said REST API works with objects, not actions? In REST any object your server interacts with is called a resource. Your job is to properly "address" that resource so the client can find it. That's where the URI comes into play.

URI (Uniform Resource Identifier) — it's the unique address for a resource on your server. To make it simpler: if your server is a big warehouse, the URI is the shelf address where the box (your resource) sits.

Example of a simple URI:

https://api.example.com/users

How to design URIs the right way?

Let's agree up front: a URI is not something "ad-hoc". It's like your storefront — it needs to be clear and tell potential users what you're offering.

Here are some tips:

1. Use nouns, not verbs.
   • Correct: /users, /products/{productId}/reviews.
   • Wrong: /getUsers, /deleteProduct.
2. Use plural for resource collections.
   • For example, /users to represent all users.
3. Use hierarchy for nested resources.
   • For example, if you want orders for a specific user: /users/{userId}/orders.
4. URI is not verbs or actions. You express actions via HTTP methods (more on that soon).

Example:

GET https://api.example.com/users
POST https://api.example.com/users
GET https://api.example.com/users/123

HTTP Methods: REST's main players

HTTP methods are the main operators for working with resources in a REST API.

REST API is strict in its simplicity. If you want to add a new user, use POST. Want to delete them? Use DELETE. And if you suddenly decide to update their phone by adding a request like GET /users/updatePhone?id=123, the karma of your REST API will be irreparably ruined.

Example: Managing users with HTTP methods

GET    /users         - Get all users
POST   /users         - Create a new user
GET    /users/123     - Get a specific user
PUT    /users/123     - Fully update user 123
PATCH  /users/123     - Update only part of user 123's data
DELETE /users/123     - Delete user 123

If the API were a mobile app, HTTP methods would be the "Add", "Delete", "Update" buttons.

HTTP response codes: your friends in debugging

When the server receives a request, it needs to tell the client the result of the operation. That's exactly why HTTP response codes exist. They're grouped, and there's no ambiguity.

Key codes you need to know

2xx: successful codes

• 200 OK: everything went smoothly. The server returned data.
• 201 Created: your resource was successfully created.
• 204 No Content: the request was processed, but there's nothing to return.

4xx: client errors

• 400 Bad Request: something's wrong with the request (for example, invalid JSON).
• 401 Unauthorized: you're not authorized.
• 403 Forbidden: you don't have permission.
• 404 Not Found: the resource wasn't found.

5xx: server errors

• 500 Internal Server Error: a generic code for a server problem.
• 503 Service Unavailable: "sorry, I'm out for lunch. Try again later."

Example of working with codes

Say you have an API for managing books:

GET /books/{bookId}

1. If the book is found, the server will return 200 OK and the book data.
2. If the book isn't found, you'll get 404 Not Found.
3. If your server decides to shoot itself in the foot, there's a good chance you'll see 500 Internal Server Error.

Wrapping up

Today we covered three main REST principles:

1. Resources and their representation via URI.
2. HTTP methods that let you interact with resources.
3. HTTP response codes that make your API friendly to the client.

Now you're ready to start building your first REST controllers. And never call an API "simple" until you've tested it with tools like Postman. REST API is simple — until a client sends a request with the parameter foo=bar&baz=<injected_script>.

In the next lecture we'll start implementing REST API controllers. Get ready for annotations, JSON, and endless "Why do I get a 404?" questions. See you!