¿Quiere crear una API REST, pero solo encuentra una teoría abstracta sobre "transferencia de estado" y "protocolos"? Cambiemos eso. Este artículo es un tutorial práctico. Diseñemos, en papel, una [API REST] real para un Administrador de tareas (lista de tareas pendientes).
Al final de esta guía, comprenderá exactamente cómo estructurar las URL, utilizar los verbos HTTP correctos y diseñar respuestas JSON profesionales.
El escenario
Creemos una API para administrar Tareas.
Una tarea tiene: id, titulo, descricao y concluida (verdadero/falso).
Paso 1: Definición de recursos (sustantivos)
En REST, pensamos en "Recursos". El recurso principal aquí es la Tarea. Las URL (Endpoints) deben representar estos recursos utilizando sustantivos en plural.
- ✅ Derecha:
/tarefas - ❌ Incorrecto:
/pegarTarefas,/criarNovaTarefa
La URL identifica QUÉ estás manipulando. El verbo HTTP identifica LA ACCIÓN.
Paso 2: enumerar y crear (la colección)
¿Cómo interactuamos con la lista completa de tareas?
Listar todas las tareas
- Solicitud:
GET /tarefas - Significado: "Hola servidor, dame la lista completa".
- Respuesta (200 OK):
[ { "id": 1, "titulo": "Comprar leite", "concluida": false }, { "id": 2, "titulo": "Lavar o carro", "concluida": true } ]
Crear una nueva tarea
- Solicitud:
POST /tarefas - Cuerpo enviado:
{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }
- Significado: "Hola servidor, agrega esto a la colección".
- Respuesta (201 Creado): El servidor debe devolver el objeto creado, ahora con el ID generado.
{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }
Paso 3: Manejo de un artículo específico
Ahora queremos cambiar la tarea ID 3.
Leer una tarea específica
- Solicitud:
GET /tarefas/3 - Respuesta (200 OK): Devuelve solo el objeto de la tarea 3.
- ¿Qué pasa si no existe?: Respuesta 404 No encontrado. (¡Es muy importante utilizar el código de error correcto!).
Actualizar una tarea (edición completa)
- Solicitud:
PUT /tarefas/3 - Cuerpo:
{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }
- Nota: PUT normalmente reemplaza el objeto completo. Si envía solo el título, el resto puede eliminarse (depende de la implementación, pero esta es la regla PUT).
Actualización parcial (PARCHE)
Para simplemente cambiar el estado a completado, sin enviar el título nuevamente.
- Solicitud:
PATCH /tarefas/3 - Cuerpo:
{ "concluida": true } - Significado: "Cambiar sólo este campo".
Eliminar una tarea
- Solicitud:
DELETE /tarefas/3 - Respuesta (204 Sin contenido): Éxito, pero no tiene nada que mostrar.
Paso 4: Filtrado y paginación
¿Y si tenemos 10.000 tareas? GET /tarefas bloquearía la aplicación.
Usamos Parámetros de consulta (lo que aparece después de ?) para filtrar. Esto no cambia la URL del recurso, simplemente filtra su vista.
- Paginación:
GET /tarefas?pagina=2&limite=10 - Filtro:
GET /tarefas?concluida=true(Solo dame los completos). - Buscar:
GET /tarefas?busca=leite
Códigos de estado HTTP (comentarios)
Una API RESTful debe usar códigos HTTP para informarle lo que sucedió. No siempre devuelva 200 con {"erro": "deu ruim"} en JSON. Esto rompe las herramientas de monitoreo.
- 200 OK: Funcionó.
- 201 Creado: Creé exitosamente el recurso (usado en POST).
- 204 Sin contenido: Funcionó, pero no tengo nada que mostrarte (usado en BORRAR).
- 400 Solicitud incorrecta: Enviaste datos incorrectos (por ejemplo, faltaba el título).
- 401 No autorizado: ¿Quién eres? (Falta ficha).
- 403 Prohibido: Sé quién eres, pero no puedes meterte con eso.
- 404 No encontrado: No lo encontré.
- Error interno del servidor 500: El servidor explotó (culpa del desarrollador backend).
Conclusión
El diseño de una API REST se trata de organización y estandarización. Siguiendo este patrón (sustantivos en la URL, verbos HTTP en la acción, códigos de estado correctos), crea una API que cualquier desarrollador del mundo entiende intuitivamente, sin tener que leer un manual de 500 páginas.
Ahora es tu turno: ¡toma este modelo y aplícalo en tu próximo proyecto!