REST APIs Explained with Real-World Examples

In today’s interconnected digital world, APIs, particularly RESTful ones, are the silent workhorses powering everything from your weather app to social media feeds. They allow different software applications to talk to each other in a standardized way. Let’s break down what they are and how they work with tangible examples you can try.

What is a REST API?

REST, or Representational State Transfer, is an architectural style for designing networked applications. It relies on a stateless, client-server communication protocol, almost always HTTP. Think of it as a set of rules for building web services. A REST API exposes resources (like a user, a blog post, or a product) that can be accessed and manipulated using standard HTTP methods. The key principles include using a uniform interface (HTTP verbs), stateless interactions, and resources identified by URLs.

Core HTTP Methods in Action

The power of REST lies in its use of standard HTTP verbs to perform operations, known as CRUD (Create, Read, Update, Delete). Here’s how they map:

GET: Retrieve data. Example: Fetching a user’s profile. GET /api/users/123
POST: Create a new resource. Example: Submitting a new comment. POST /api/comments
PUT/PATCH: Update a resource. PUT often replaces it, PATCH updates partially. PATCH /api/users/123 { "name": "New Name" }
DELETE: Remove a resource. DELETE /api/posts/456

A Real-World Example with JSONPlaceholder

The best way to understand is to interact with a live API. We’ll use JSONPlaceholder, a free fake API for testing. You can run these commands in your terminal using curl.

GET a list of posts: This fetches all blog posts.
```
curl https://jsonplaceholder.typicode.com/posts
```
You’ll receive a JSON array of post objects, each with an id, title, and body.
GET a single post: Retrieve a specific post by its ID.
```
curl https://jsonplaceholder.typicode.com/posts/1
```
This returns just the JSON for the post with id: 1.

POST to create a new post: Send data to create a resource.

curl -X POST https://jsonplaceholder.typicode.com/posts \
-H 'Content-Type: application/json' \
-d '{"title": "My New Post", "body": "This is the content", "userId": 1}'

The API will respond with the newly created post object, including a generated id (like 101).

Understanding the Response: Status Codes & JSON

When you make a request, the API responds with a status code and usually a body. Key HTTP status codes include:

200 OK: Success.
201 Created: Resource created successfully (common for POST).
404 Not Found: The requested resource doesn’t exist.
500 Internal Server Error: Something went wrong on the server.

The data is typically returned in JSON (JavaScript Object Notation), a lightweight, human-readable format. In our examples, the response body was JSON, which applications easily parse to extract the title, id, or other properties.

REST APIs provide a predictable and scalable way for systems to exchange data. By leveraging the existing HTTP protocol, they simplify integration, allowing developers to build complex, feature-rich applications by combining services. Start experimenting with public APIs like JSONPlaceholder—it’s the most effective way to move from theory to practice.