Do you want to build a REST API, but only find abstract theory about "state transfer" and "protocols"? Let's change that. This article is a practical tutorial. Let's design, on paper, a real [REST API] for a Task Manager (To-Do List).
By the end of this guide, you'll understand exactly how to structure URLs, use the correct HTTP verbs, and design professional JSON responses.
The Scenario
Let's create an API to manage Tasks.
A task has: id, titulo, descricao and concluida (true/false).
Step 1: Defining Resources (Nouns)
In REST, we think about "Resources". The main resource here is the Task. URLs (Endpoints) must represent these resources using plural nouns.
- ✅ Right:
/tarefas - ❌ Wrong:
/pegarTarefas,/criarNovaTarefa
The URL identifies WHAT you are manipulating. The HTTP verb identifies THE ACTION.
Step 2: List and Create (The Collection)
How do we interact with the complete task list?
List all tasks
- Request:
GET /tarefas - Meaning: "Hey server, give me the complete list."
- Response (200 OK):
[ { "id": 1, "titulo": "Comprar leite", "concluida": false }, { "id": 2, "titulo": "Lavar o carro", "concluida": true } ]
Create a new task
- Requisition:
POST /tarefas - Body sent:
{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }
- Meaning: "Hey server, add this to collection."
- Response (201 Created): The server must return the created object, now with the generated ID.
{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }
Step 3: Handling a Specific Item
Now we want to change the ID 3 task.
Read a specific task
- Requisition:
GET /tarefas/3 - Response (200 OK): Returns only the object from task 3.
- What if it doesn't exist?: Response 404 Not Found. (Very important to use the right error code!).
Update a task (Full Edition)
- Requisition:
PUT /tarefas/3 - Body:
{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }
- Note: PUT usually replaces the entire object. If you send just the title, the rest may be deleted (it depends on the implementation, but this is the PUT rule).
Partially update (PATCH)
To just change the status to completed, without sending the title again.
- Requisition:
PATCH /tarefas/3 - Body:
{ "concluida": true } - Meaning: "Change this field only".
Delete a task
- Requisition:
DELETE /tarefas/3 - Response (204 No Content): Success, but has nothing to show back.
Step 4: Filtering and Pagination
What if we have 10,000 tasks? GET /tarefas would crash the app.
We use Query Parameters (the thing after ?) to filter. This doesn't change the URL of the resource, it just filters the view of it.
- Pagination:
GET /tarefas?pagina=2&limite=10 - Filter:
GET /tarefas?concluida=true(Just give me the completed ones). - Search:
GET /tarefas?busca=leite
HTTP Status Codes (Feedback)
A RESTful API must use HTTP codes to tell you what happened. Don't always return 200 with {"erro": "deu ruim"} in JSON. This breaks monitoring tools.
- 200 OK: It worked.
- 201 Created: I successfully created the resource (used in POST).
- 204 No Content: It worked, but I have nothing to show you (used in DELETE).
- 400 Bad Request: You sent wrong data (e.g. the title was missing).
- 401 Unauthorized: Who are you? (Missing token).
- 403 Forbidden: I know who you are, but you're not allowed to mess with it.
- 404 Not Found: I didn't find it.
- 500 Internal Server Error: The server exploded (backend developer's fault).
Conclusion
Designing a REST API is about organization and standardization. By following this pattern (Nouns in the URL, HTTP Verbs in the action, Correct Status Codes), you create an API that any developer in the world understands intuitively, without having to read a 500-page manual.
Now it's your turn: take this model and apply it to your next project!