REST APIs are the unsung heroes of modern software, but often misunderstood as just "ways for apps to talk."
Let’s see one in action. Imagine you’re building a simple to-do list app. Your backend has a list of tasks. Here’s how your frontend might ask for them using a REST API.
curl -X GET http://localhost:3000/tasks
This curl command is like a client (your frontend) sending a message. GET is the method, telling the server what you want to do. /tasks is the resource, the specific thing you want to interact with. The server, if it’s set up correctly, will respond.
A successful response for our /tasks resource might look like this:
[
{"id": 1, "description": "Buy groceries", "completed": false},
{"id": 2, "description": "Walk the dog", "completed": true}
]
This JSON is a representation of the resource. It’s a list of tasks, each with an ID, description, and completion status. The API is just a structured way to access and manipulate these resources.
The power of REST lies in its constraints, which make it predictable and scalable. The core idea is to treat everything as a resource. A resource can be anything: a user, a product, a document, or in our case, a list of tasks. You then use standard HTTP methods to perform actions on these resources.
The most common HTTP methods are:
- GET: Retrieve a representation of a resource. (e.g.,
GET /tasksto get all tasks,GET /tasks/1to get task with ID 1). - POST: Create a new resource. (e.g.,
POST /taskswith a JSON body containing the new task’s description). - PUT: Update an existing resource entirely. (e.g.,
PUT /tasks/1with a JSON body containing the updated task details). - PATCH: Partially update an existing resource. (e.g.,
PATCH /tasks/1with a JSON body like{"completed": true}). - DELETE: Remove a resource. (e.g.,
DELETE /tasks/1).
Each request and response also comes with a status code, a three-digit number indicating the outcome of the request. These are standardized and give immediate feedback.
- 2xx (Success):
200 OK(standard success),201 Created(resource successfully created). - 3xx (Redirection):
301 Moved Permanently(resource has moved). - 4xx (Client Error):
400 Bad Request(malformed request),401 Unauthorized(authentication required),404 Not Found(resource doesn’t exist). - 5xx (Server Error):
500 Internal Server Error(unexpected server issue),503 Service Unavailable(server is down or overloaded).
When you make a POST request to create a new task, you send data to the server:
curl -X POST -H "Content-Type: application/json" -d '{"description": "Schedule dentist appointment"}' http://localhost:3000/tasks
If successful, the server might respond with:
HTTP/1.1 201 Created
Location: http://localhost:3000/tasks/3
Content-Type: application/json
{"id": 3, "description": "Schedule dentist appointment", "completed": false}
Notice the 201 Created status code and the Location header, which tells you where the newly created resource can be found.
The "RESTful" nature of an API is about adhering to these principles: client-server separation, statelessness (each request is independent), cacheability, a uniform interface, and layered systems. This leads to APIs that are flexible, robust, and easy to evolve. Many developers think that if an API uses HTTP methods and URLs, it’s RESTful. This is a misconception. A truly RESTful API is one that’s designed around the concept of resources and uses the HTTP methods and status codes in a way that reflects the underlying state transitions of those resources, rather than just mapping HTTP verbs to CRUD operations.
The next thing you’ll likely grapple with is how to handle authentication and authorization in your API interactions.