What Is a REST API and How Does It Work for Beginners

You've probably heard the terms "API" or "REST API" often in the programming world, but you might still be confused about what they actually mean and how they work. Don't worry — in this article we'll cover REST API from scratch in easy-to-understand language, complete with analogies and examples that make it clearer.

What Is an API?

API stands for Application Programming Interface. Simply put, an API is a way for two applications to "talk" to each other. Imagine you're at a restaurant. You don't walk straight into the kitchen to get the food yourself — you order through a waiter. That waiter is the API: an intermediary that takes your request, delivers it to the system in the back (the kitchen/server), then returns the result to you.

A real-world example: when the weather app on your phone shows the forecast, it uses an API to request weather data from the weather service provider's server.

What Is REST?

REST stands for Representational State Transfer. It is an architectural style (not a protocol or standard) that defines the rules and principles for building APIs using HTTP. An API that follows REST principles is called a RESTful API or REST API.

REST became popular because of its simplicity — it uses the existing HTTP protocol and doesn't require a special framework to be used.

The Main Principles of REST API

There are several principles that make an API "RESTful":

• Client-Server — the client (frontend/app) and server (backend) are separate and communicate through the API
• Stateless — each request stands alone; the server doesn't store information about previous requests
• Uniform Interface — uses consistent formats and conventions (URLs, HTTP methods)
• Resource-based — everything accessed is treated as a "resource" identified by a URL

The Concept of Resources and Endpoints

In a REST API, every "thing" that can be accessed is called a resource. For example, in a blog application, the resources could be articles, users, or comments. Each resource is accessed through an endpoint — a specific URL.

Example endpoints for the article resource:

GET    /api/articles        → get all articles
GET    /api/articles/5      → get the article with ID 5
POST   /api/articles        → create a new article
PUT    /api/articles/5      → update the article with ID 5
DELETE /api/articles/5      → delete the article with ID 5

Notice how the URL represents the "thing" (the article) and the HTTP method represents the "action" performed.

HTTP Methods in a REST API

A REST API uses HTTP methods to determine the type of operation performed:

• GET — read or retrieve data (Read)
• POST — create new data (Create)
• PUT — update the entire existing record (Update)
• PATCH — update part of the existing record (Partial Update)
• DELETE — delete data (Delete)

Data Format: JSON

A REST API generally uses JSON (JavaScript Object Notation) as the data format for requests and responses. JSON is easy for humans to read and easy for machines to process. Example response from the endpoint GET /api/articles/5:

{
  "id": 5,
  "title": "Learning REST API",
  "content": "A REST API is...",
  "author": "Budi",
  "date": "2024-01-15"
}

How to Use a REST API

To communicate with a REST API, you need an HTTP client. Some popular options:

• Postman or Insomnia — GUI tools for testing APIs, great for beginners
• cURL — a command-line tool available on almost every operating system
• Fetch API or Axios — for using a REST API from JavaScript in the browser or Node.js

Example using the Fetch API in JavaScript to retrieve article data:

fetch('https://api.example.com/articles')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Status Codes in a REST API

A REST API uses HTTP status codes to tell the client whether the request succeeded or failed:

• 200 OK — the request succeeded, data returned
• 201 Created — new data created successfully
• 400 Bad Request — invalid request or wrong data sent
• 401 Unauthorized — login/authentication required first
• 403 Forbidden — no permission to access this resource
• 404 Not Found — the requested resource wasn't found
• 500 Internal Server Error — there's a problem on the server side

Public REST APIs to Learn With

The best way to learn a REST API is to try it directly. Some public REST APIs you can explore for free:

• JSONPlaceholder (jsonplaceholder.typicode.com) — a fake API for testing
• OpenWeatherMap API — global weather data
• GitHub API — access GitHub repository and user data
• The Dog API / Cat API — for fun, simple practice

Conclusion

A REST API is the standard way applications use to communicate with each other over HTTP. By understanding the concepts of resources, endpoints, HTTP methods, JSON, and status codes, you already have a strong basic understanding of REST APIs. The next step is to practice directly — try using a public API, then learn how to build one yourself using your favorite backend framework. REST API is a highly sought-after skill in the industry, so the time you invest in learning it won't be wasted!