Tema 14 · APIs REST & Resources

14. Construcción de APIs RESTful: API Resource Controllers, Serialización JSON y Códigos HTTP

Diseña endpoints profesionales con formato JSON estándar, capas de transformación con JsonResource y respuestas HTTP semánticas (200, 201, 404).

Laravel como Backend para APIs REST

Laravel es uno de los motores de backend más utilizados para alimentar aplicaciones móviles (iOS/Android) y Single Page Applications (React, Vue, Svelte, Angular). Para construir APIs, las rutas se definen en routes/api.php (con prefijo automático /api/...).

A diferencia de una vista web, una API no devuelve HTML, sino estructuras de datos en formato JSON acompañadas de códigos de estado HTTP semánticos (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Unprocessable Entity).

Controladores API (--api)

En una API RESTful no necesitamos los métodos create() ni edit() (ya que no devolvemos formularios HTML). Por ello, Artisan provee la bandera --api:

php artisan make:controller Api/CursoApiController --api

Y en routes/api.php se registra con:

Route::apiResource('cursos', Api\CursoApiController::class);

Capa de Transformación con API Resources (JsonResource)

Error común de principiante: Retornar directamente el modelo Eloquent con return response()->json(User::all()). Esto expone accidentalmente columnas de base de datos internas (como contraseñas, tokens o nombres de columnas SQL que acoplan el frontend a la base de datos).

La solución profesional es crear un API Resource, que actúa como una capa de transformación intermedia:

php artisan make:resource CursoResource

En app/Http/Resources/CursoResource.php defines la estructura exacta del JSON:

public function toArray(Request $request): array
{
    return [
        'id'          => $this->id,
        'titulo'      => $this->title,
        'precio_formato' => '$' . number_format($this->price_cop, 0),
        'instructor'  => [
            'nombre'  => $this->instructor->name,
            'correo'  => $this->instructor->email,
        ],
        'creado_el'   => $this->created_at->toIso8601String(),
    ];
}

⚡ Controlador API REST Completo con JsonResponse y Resource

Endpoints de listado, creación y detalle con códigos de estado HTTP 200 y 201.

CursoApiController.php
Solo lectura
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Curso;
use App\Http\Resources\CursoResource;
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Resources\Json\AnonymousResourceCollection;

class CursoApiController extends Controller
{
    /** Listado paginado de cursos en formato JSON */
    public function index(): AnonymousResourceCollection
    {
        $cursos = Curso::with('instructor')
            ->where('is_active', true)
            ->paginate(15);

        return CursoResource::collection($cursos);
    }

    /** Crea un nuevo curso y retorna HTTP 201 Created */
    public function store(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'title'     => 'required|string|max:190',
            'slug'      => 'required|string|unique:cursos,slug',
            'summary'   => 'required|string|max:300',
            'price_cop' => 'required|numeric|min:0',
        ]);

        $curso = Curso::create($validated);

        return response()->json([
            'status'  => 'success',
            'message' => 'Curso creado exitosamente',
            'data'    => new CursoResource($curso),
        ], 201);
    }

    /** Detalle de un curso específico */
    public function show(Curso $curso): CursoResource
    {
        return new CursoResource($curso->load('instructor', 'lecciones'));
    }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Cuál es la función principal de un API Resource (JsonResource) en Laravel?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Laravel Framework Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.