Understanding REST APIs: A Visual Guide

What is a REST API?

REST stands for Representational State Transfer. It is an architectural style for designing networked applications. When you use an app on your phone that fetches data from a server, there is a good chance it is using a REST API behind the scenes.

Think of a REST API as a waiter in a restaurant. You (the client) cannot go into the kitchen (the server) yourself. Instead, you tell the waiter what you want, the waiter takes your request to the kitchen, and brings back what you ordered. The API is the waiter that communicates between you and the server.

HTTP Methods: The Four Basic Actions

Every interaction with a REST API uses one of four HTTP methods. Each method represents a different action you want to perform on the data.

GET retrieves data. When you load a webpage or fetch a list of users, that is a GET request. GET should never change anything on the server. It is read-only.

POST creates new data. When you submit a form to create a new account or post a comment, that is a POST request. The server receives your data and creates a new resource.

PUT updates existing data. When you edit your profile information or change the title of a blog post, that is a PUT request. You are replacing the existing data with new data.

DELETE removes data. When you delete a comment or remove an item from your cart, that is a DELETE request. The server removes the specified resource.

Endpoints: Where to Find Things

Endpoints are the URLs that represent different resources in your API. A well-designed API uses intuitive URL patterns. For example, an API for a blog might have these endpoints:

GET /api/posts - Get all posts
GET /api/posts/5 - Get post with ID 5
POST /api/posts - Create a new post
PUT /api/posts/5 - Update post 5
DELETE /api/posts/5 - Delete post 5

Notice how the URL structure tells you what resource you are working with, and the HTTP method tells you what action you want to perform.

Status Codes: Did It Work?

Every API response includes a status code that tells you what happened. Here are the most common ones you should know:

200 OK - Everything worked. The request was successful.

201 Created - A new resource was successfully created.

400 Bad Request - Something was wrong with your request. Maybe you sent invalid data or forgot a required field.

401 Unauthorized - You need to authenticate. The server does not know who you are.

403 Forbidden - You are authenticated but not allowed to do this. You know who you are, but you do not have permission.

404 Not Found - The resource does not exist. You requested something that is not there.

500 Internal Server Error - Something went wrong on the server. This is not your fault. The server had a problem processing your request.

Request and Response Format

REST APIs typically use JSON (JavaScript Object Notation) for sending and receiving data. JSON is lightweight and easy to read. A typical request might include headers with authentication tokens and a body with the data you are sending.

A response from the API usually contains the status code, some headers, and a body with the data you requested. For example, a GET request to fetch a user might return a JSON object with the user's name, email, and other details.

Understanding how to read and construct these requests and responses is fundamental to working with any API.

Try It Yourself

The best way to understand REST APIs is to use one. Go to a free API like JSONPlaceholder (jsonplaceholder.typicode.com) and use a tool like Postman or even your browser to make requests. Create a post, fetch a list of users, and delete a comment.

Once you see how the requests and responses work in practice, the concepts click into place. REST is not complicated. It is a set of conventions that make APIs predictable and easy to use.