Documentación de la API del Blog

Esta es la documentación para la API del blog. Todos los endpoints están prefijados con /api.

Autenticación

Las rutas protegidas requieren un token de autenticación de Sanctum. Este token debe ser enviado en la cabecera de la solicitud:

Authorization: Bearer <token>

1. Registro de Usuario

Endpoint: POST /api/register
Descripción: Registra un nuevo usuario en el sistema.
Autenticación: No requerida.

Cuerpo de la Solicitud (Request Body):

{
    "name": "Nuevo Usuario",
    "email": "nuevo@example.com",
    "password": "password123",
    "password_confirmation": "password123"
}

Respuesta Exitosa (201 Created):

{
    "user": {
        "name": "Nuevo Usuario",
        "email": "nuevo@example.com",
        "updated_at": "2023-10-27T10:00:00.000000Z",
        "created_at": "2023-10-27T10:00:00.000000Z",
        "id": 11
    },
    "token": "1|aBcDeFgHiJkLmNoPqRsTuVwXyZ123456"
}

2. Inicio de Sesión

Endpoint: POST /api/login
Descripción: Autentica a un usuario y devuelve un token de acceso.
Autenticación: No requerida.

Cuerpo de la Solicitud (Request Body):

{
    "email": "test@example.com",
    "password": "password"
}

Respuesta Exitosa (200 OK):

{
    "user": {
        "id": 1,
        "name": "Usuario de Prueba",
        "email": "test@example.com",
        "email_verified_at": null,
        "created_at": "2023-10-27T09:00:00.000000Z",
        "updated_at": "2023-10-27T09:00:00.000000Z"
    },
    "token": "2|aBcDeFgHiJkLmNoPqRsTuVwXyZ123457"
}

Respuesta de Error (401 Unauthorized):

{
    "message": "Credenciales inválidas"
}

3. Cierre de Sesión

Endpoint: POST /api/logout
Descripción: Invalida el token de autenticación del usuario actual.
Autenticación: Requerida.

Respuesta Exitosa (200 OK):

{
    "message": "Cierre de sesión exitoso."
}

4. Cambiar Contraseña

Endpoint: POST /api/change-password
Descripción: Permite al usuario autenticado cambiar su contraseña.
Autenticación: Requerida.

Cuerpo de la Solicitud (Request Body):

{
    "current_password": "password",
    "new_password": "new_password123",
    "new_password_confirmation": "new_password123"
}

Respuesta Exitosa (200 OK):

{
    "message": "Contraseña cambiada exitosamente."
}

Respuesta de Error (422 Unprocessable Entity):

{
    "message": "La contraseña actual es incorrecta.",
    "errors": {
        "current_password": [
            "La contraseña actual es incorrecta."
        ]
    }
}

Posteos

1. Listar Posteos

Endpoint: GET /api/posteos
Descripción: Devuelve una lista paginada de posteos. Se puede filtrar por categoría y ordenar.
Autenticación: No requerida.
Parámetros de Query (Opcionales):
- page: Número de página (ej: ?page=2).
- sort: Ordena los resultados. Valores: latest (defecto), oldest (ej: ?sort=oldest).
- category_id: Filtra por el ID de una categoría (ej: ?category_id=5).
- titulo: Filtra los posteos buscando un texto dentro del título (búsqueda parcial). (ej: ?titulo=guia)

Respuesta Exitosa (200 OK):

La respuesta ahora incluye la lista de posteos paginada en el objeto data y un objeto adicional last_post que siempre contiene el último posteo creado en toda la base de datos, sin importar los filtros aplicados.

{
    "data": [
        {
            "id": 1,
            "titulo": "Título del Posteo",
            "descripcion": "Una breve descripción o resumen del posteo.",
            "contenido": "Contenido del posteo...",
            "fecha_publicacion": "2023-10-26T18:30:00.000000Z",
            "autor": {
                "id": 1,
                "name": "Usuario de Prueba"
            },
            "categorias": [
                {
                    "id": 5,
                    "nombre": "Tecnología"
                }
            ],
            "imagenes": [
                {
                    "id": 1,
                    "url": "http://example.com/imagen1.jpg"
                }
            ]
        }
    ],
    "links": {
        "first": "http://localhost/api/posteos?page=1",
        "last": "http://localhost/api/posteos?page=10",
        "prev": null,
        "next": "http://localhost/api/posteos?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "path": "http://localhost/api/posteos",
        "per_page": 15,
        "to": 15,
        "total": 150
    },
    "last_post": {
        "id": 500,
        "titulo": "El posteo más reciente de todos",
        "descripcion": "Descripción del último post...",
        "contenido": "Contenido del último post...",
        "fecha_publicacion": "2023-10-27T15:00:00.000000Z",
        "autor": {
            "id": 7,
            "name": "Autor Siete"
        },
        "categorias": [
            {
                "id": 12,
                "nombre": "Noticias"
            }
        ],
        "imagenes": [
            {
                "id": 99,
                "url": "http://example.com/img99.jpg"
            }
        ]
    }
}

2. Ver un Posteo

Endpoint: GET /api/posteos/{posteo}
Descripción: Muestra un posteo específico por su ID.
Autenticación: No requerida.

Respuesta Exitosa (200 OK):

{
    "data": {
        "id": 1,
        "titulo": "Título del Posteo",
        "descripcion": "Una breve descripción o resumen del posteo.",
        "contenido": "Contenido del posteo...",
        "fecha_publicacion": "2023-10-26T18:30:00.000000Z",
        "autor": {
            "id": 1,
            "name": "Usuario de Prueba"
        },
        "categorias": [
            {
                "id": 5,
                "nombre": "Tecnología"
            }
        ],
        "imagenes": [
            {
                "id": 1,
                "url": "http://example.com/imagen1.jpg"
            }
        ]
    }
}

3. Crear un Posteo

Endpoint: POST /api/posteos
Descripción: Crea un nuevo posteo.
Autenticación: Requerida.

Cuerpo de la Solicitud (Request Body):

{
    "titulo": "Mi Nuevo Posteo",
    "descripcion": "Esta es la descripción de mi nuevo posteo.",
    "contenido": "Este es el contenido de mi nuevo posteo.",
    "fecha_de_publicacion": "2023-11-15 10:00:00",
    "urls_imagenes": [
        "http://example.com/imagen_nueva_1.jpg",
        "http://example.com/imagen_nueva_2.jpg"
    ],
    "categorias": [1, 5]
}

Respuesta Exitosa (201 Created): (La estructura es la misma que al ver un posteo)

4. Actualizar un Posteo

Endpoint: PUT /api/posteos/{posteo}
Descripción: Actualiza un posteo existente. Solo el autor puede hacerlo.
Autenticación: Requerida.

Cuerpo de la Solicitud (Request Body): (Todos los campos son opcionales)

{
    "titulo": "Título Actualizado",
    "descripcion": "Descripción actualizada.",
    "contenido": "Contenido actualizado.",
    "urls_imagenes": [
        "http://example.com/imagen_actualizada.jpg"
    ],
    "categorias": [5, 8]
}

Respuesta Exitosa (200 OK): (La estructura es la misma que al ver un posteo)

Respuesta de Error (403 Forbidden):

{
    "message": "No autorizado para realizar esta acción."
}

5. Eliminar un Posteo

Endpoint: DELETE /api/posteos/{posteo}
Descripción: Elimina un posteo. Solo el autor puede hacerlo.
Autenticación: Requerida.

Respuesta Exitosa (204 No Content): (Sin cuerpo de respuesta)

Categorías

1. Listar Categorías

Endpoint: GET /api/categorias
Descripción: Devuelve una lista de todas las categorías.
Autenticación: No requerida.

Respuesta Exitosa (200 OK):

[
    {
        "id": 1,
        "nombre": "Viajes"
    },
    {
        "id": 2,
        "nombre": "Tecnología"
    }
]

2. Ver una Categoría

Endpoint: GET /api/categorias/{categoria}
Descripción: Muestra una categoría específica por su ID.
Autenticación: No requerida.

Respuesta Exitosa (200 OK):

{
    "id": 1,
    "nombre": "Viajes"
}

3. Crear una Categoría

Endpoint: POST /api/categorias
Descripción: Crea una nueva categoría.
Autenticación: Requerida.

Cuerpo de la Solicitud (Request Body):

{
    "nombre": "Gastronomía"
}

Respuesta Exitosa (201 Created):

{
    "id": 21,
    "nombre": "Gastronomía"
}

Respuesta de Error (422 Unprocessable Entity):

{
    "message": "The nombre has already been taken.",
    "errors": {
        "nombre": [
            "The nombre has already been taken."
        ]
    }
}

4. Actualizar una Categoría

Endpoint: PUT /api/categorias/{categoria}
Descripción: Actualiza el nombre de una categoría existente.
Autenticación: Requerida.

Cuerpo de la Solicitud (Request Body):

{
    "nombre": "Cocina Internacional"
}

Respuesta Exitosa (200 OK):

{
    "id": 21,
    "nombre": "Cocina Internacional"
}

5. Eliminar una Categoría

Endpoint: DELETE /api/categorias/{categoria}
Descripción: Elimina una categoría.
Autenticación: Requerida.

Respuesta Exitosa (204 No Content): (Sin cuerpo de respuesta)