openapi.yaml

openapi: 3.0.3
info:
  title: Q-rs
  description: Endpoints para q-rs.
  version: 1.0.1
tags:
  - name: Authentication
    description: Endpoints relacionados con el inicio y cierre de sesión.
  - name: Accounts
    description: Endpoints relacionados con el manejo de cuentas y perfiles
  - name: Links
    description: Endpoints relacionados con creación y manejo de enlaces.
  - name: Campaigns
    description: Endpoints relacionados con el manejo de campañas.
paths:
  /login:
    post:
      tags:
        - Authentication
      summary: Iniciar sesión
      description: Permite autenticar al usuario mediante email y contraseña. Si se requiere MFA, se indica en la respuesta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: user@example.com
                password:
                  type: string
                  example: securepassword
                mfa:
                  type: integer
                  nullable: true
                  example: null
      responses:
        '204':
          description: Completado. La sesión fue iniciada correctamente y se estableció una cookie de sesión.
        '401':
          description: Credenciales inválidas. El correo o contraseña no coinciden con un usuario registrado.
        '400':
          description: Se requiere autenticación 2FA.

  /logout:
    get:
      tags:
        - Authentication
      summary: Cerrar sesión
      description: Permite al usuario cerrar su sesión activa.
      responses:
        '204':
          description: Sesión cerrada correctamente.
        '401':
          description: No hay una sesión activa.

  /signup:
    post:
      tags:
        - Authentication
      summary: Crear cuenta
      description: Permite a un usuario registrarse proporcionando un nombre de usuario, correo electrónico y contraseña.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: new_user
                email:
                  type: string
                  example: user@example.com
                password:
                  type: string
                  example: securepassword
      responses:
        '204':
          description: Usuario creado exitosamente.
        '403':
          description: El usuario ya existe.
        '400':
          description: El cuerpo de la solicitud no contiene todos los campos requeridos.

  /account/settings:
    get:
      tags:
        - Accounts
      summary: Obtener configuración de la cuenta
      description: Devuelve la configuración actual de la cuenta del usuario.
      responses:
        '200':
          description: Configuración de la cuenta obtenida correctamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    example: sergio_ribera
                  email:
                    type: string
                    example: sergio@rustlang-es.org
                  language:
                    type: string
                    example: "es-ES"
                  notifications:
                    type: boolean
                    example: true
        '401':
          description: No hay una sesión activa.

    put:
      tags:
        - Accounts
      summary: Editar configuración de la cuenta
      description: Actualiza la configuración de la cuenta del usuario.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                language:
                  type: string
                  example: "es-ES"
                notifications:
                  type: boolean
                  example: true
      responses:
        '204':
          description: Configuración actualizada correctamente.
        '401':
          description: No hay una sesión activa.

  /account/profile:
    patch:
      tags:
        - Accounts
      summary: Actualizar datos personales
      description: Permite al usuario actualizar su información personal como nombre o correo electrónico.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: "sergio_ribera"
                email:
                  type: string
                  example: "sergio@rustlang-es.org"
      responses:
        '204':
          description: Perfil modificado correctamente.
        '401':
          description: No hay una sesión activa.

  /account/profile/avatar:
    post:
      tags:
        - Accounts
      summary: "Actualiza tu avatar de perfil"
      description: "Permite al usuario cargar una nueva imagen de avatar para su perfil."
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar:
                  type: string
                  format: binary
                  description: "Selecciona y carga una imagen para actualizar tu avatar."
      responses:
        '204':
          description: Avatar modificado correctamente.
        '401':
          description: No hay una sesión activa.

  /account/password:
    put:
      tags:
        - Accounts
      summary: Cambiar contraseña
      description: Cambia la contraseña del usuario.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currentPassword:
                  type: string
                newPassword:
                  type: string
      responses:
        '204':
          description: Contraseña actualizada.
        '401':
          description: No hay una sesión activa.
        '403':
          description: Contraseña incorrecta.

  /account/deactivate:
    post:
      tags:
        - Accounts
      summary: Desactivar cuenta
      description: Desactiva la cuenta del usuario con 30 días de antelación antes de proceder con su eliminación definitiva.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
      responses:
        '204':
          description: Cuenta desactivada.
        '401':
          description: No hay una sesión activa.
        '403':
          description: Contraseña incorrecta.


  /links:
    get:
      tags:
        - Links
      summary: Obtener enlaces.
      description: Permite obtener todos los enlaces creados por el usuario.
      responses:
        '200':
          description: Links recuperados exitosamente.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                      id:
                        type: integer
                        example: 2382
                      slug:
                        type: string
                        example: abcdef
                      content:
                        oneOf:
                          - type: array
                            example:
                              - https://rustlang.org
                              - https://rustlang-es.org
                          - type: string
                            example: https://rustlang-es.org
                      created_at:
                        type: integer
                        example: 1732289376
                      modified_at:
                        type: integer
                        nullable: true
                        example: 1732289376
                      campaign:
                        type: string
                        nullable: true
                        example: event2025
                      tags:
                        type: array
                        nullable: true
                        items:
                          type: string
                        example:
                          - events
                          - "2025"
                          - upcoming

        '401':
          description: No hay una sesión activa

    put:
      tags: 
        - Links
      summary: Crear un nuevo enlace.
      description: Permite crear un nuevo enlace con un slug aleatorio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  oneOf:
                    - type: string
                      format: string
                      description: Un único enlace.
                      example: https://rustlang-es.org
                    - type: array
                      items:
                        type: string
                        format: string
                      description: Una lista de enlaces.
                      example: 
                        - https://rustlang.org
                        - https://rustlang-es.org
                tags:
                  type: array
                  items:
                    type: string
                    format: string
                  description: array de nombres de etiquetas
                  nullable: true
                  example: 
                    - tag1
                    - tag2
                campaign:
                  type: string
                  description: Nombre de la campaña
                  nullable: true
                  example: event2025

      responses:
        '200':
          description: Link creado exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
                      example: Link created
                    slug:
                      type: string
                      example: abcdef
                    created_at:
                      type: integer
                      example: 1732289376
        '401':
          description: No hay una sesión activa

  /links/{slug}:
    parameters:
      - name: slug
        in: path
        required: true
        description: El identificador único del enlace.
        schema:
          type: string
    get:
      tags:
        - Links
      summary: Obtener enlace por slug
      description: Permite obtener un enlace específico utilizando su slug.
      responses:
        '200':
          description: Link recuperado exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                    id:
                      type: integer
                      example: 2382
                    content:
                      oneOf:
                        - type: array
                          example:
                            - https://rustlang.org
                            - https://rustlang-es.org
                        - type: string
                          example: https://rustlang-es.org
                    created_at:
                      type: integer
                      example: 1732289376
                    modified_at:
                      type: integer
                      nullable: true
                      example: 1732289376
                    campaign:
                      type: string
                      nullable: true
                      example: event2025
                    tags:
                      type: array
                      nullable: true
                      items:
                        type: string
                      example:
                        - events
                        - "2025"
                        - upcoming
        '401':
          description: No hay una sesión activa.
        '403':
          description: El enlace no pertenece al usuario actual.
        '404':
          description: El enlace no existe.

    post:
      tags:
        - Links
      summary: Crear enlace con slug personalizado.
      description: Permite crear enlaces con un slug personalizado.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  oneOf:
                    - type: string
                      format: string
                      description: Un único enlace.
                      example: https://rustlang-es.org
                    - type: array
                      items:
                        type: string
                        format: string
                      description: Una lista de enlaces.
                      example: 
                        - https://rustlang.org
                        - https://rustlang-es.org
                tags:
                  type: array
                  items:
                    type: string
                    format: string
                  description: array de nombres de etiquetas
                  nullable: true
                  example: 
                    - tag1
                    - tag2
                campaign:
                  type: string
                  description: Nombre de la campaña
                  nullable: true
                  example: event2025
      responses:
        '201':
          description: Enlace creado
          content:
            application/json:
              schema:
                type: object
                properties:
                    message:
                      type: string
                      example: Link created
                    slug:
                      type: string
                      example: abcdef
                    created_at:
                      type: integer
                      example: 1732289376
        '401':
          description: No hay una sesión activa.
        '409':
          description: Ya existe.

    patch:
      tags: 
        - Links
      summary: Editar un enlace
      description: Permite modificar un enlace existente
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  oneOf:
                    - type: string
                      format: string
                      description: Un único enlace.
                      nullable: true
                      example: https://rustlang-es.org
                    - type: array
                      items:
                        type: string
                        format: string
                      description: Una lista de enlaces.
                      nullable: true
                      example: 
                        - https://rustlang.org
                        - https://rustlang-es.org
                tags:
                  type: array
                  items:
                    type: string
                    format: string
                  description: array de nombres de etiquetas
                  nullable: true
                  example: 
                    - tag1
                    - tag2
                campaign:
                  type: string
                  description: Nombre de la campaña
                  nullable: true
                  example: event2025
      responses:
        '204':
          description: Modificado.
        '401':
          description: No hay una sesión activa.
        '403':
          description: El enlace no pertenece al usuario actual.
        '404':
          description: El enlace no existe.

    delete:
      tags:
        - Links
      summary: Eliminar un enlace
      description: Permite eliminar un enlace existente utilizando su slug.
      responses:
        '204':
          description: Enlace eliminado exitosamente.
        '401':
          description: No hay una sesión activa.
        '403':
          description: El enlace no pertenece al usuario actual.
        '404':
          description: El enlace no existe.

  /campaigns:
    get:
      tags:
        - Campaigns
      summary: Obtener campañas
      description: Permite recuperar todas las campañas creadas por el usuario.
      responses:
        '200':
          description: Campañas recuperadas exitosamente.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: "event2025"
                      links:
                        type: array
                        items:
                          type: string
                          example: "abcdef"
                      created_at:
                        type: integer
                        example: 1732289376
                      modified_at:
                        type: integer
                        nullable: true
                        example: 1732289376
                      ends_at:
                        type: integer
                        nullable: true
                        example: 1732289376
        '401':
          description: No hay una sesión activa.

    put:
      tags:
        - Campaigns
      summary: Crear campaña
      description: Permite crear una nueva campaña.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Nombre de la campaña.
                  example: event2025
                ends_at:
                  type: integer
                  description: Fecha de finalización (timestamp).
                  nullable: true
                  example: 1732289376
      responses:
        '204':
          description: Campaña creada exitosamente.
        '401':
          description: No hay una sesión activa.

  /campaigns/{name}:
    parameters:
      - name: name
        in: path
        required: true
        description: El nombre único de la campaña.
        schema:
          type: string
    get:
      tags:
        - Campaigns
      summary: Obtener campaña
      description: Permite obtener una campaña específica utilizando su nombre.
      responses:
        '200':
          description: Campaña recuperada exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: "event2025"
                    links:
                      type: array
                      items:
                        type: string
                        example: "abcdef"
                    created_at:
                      type: integer
                      example: 1732289376
                    modified_at:
                      type: integer
                      nullable: true
                      example: 1732289376
                    ends_at:
                      type: integer
                      nullable: true
                      example: 1732289376
        '401':
          description: No hay una sesión activa.
        '404':
          description: La campaña especificada no existe.

    patch:
      tags:
        - Campaigns
      summary: Editar campaña
      description: Permite modificar una campaña existente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Nuevo nombre de la campaña.
                  example: event2026
                ends_at:
                  type: integer
                  description: Nueva fecha de finalización (timestamp).
                  nullable: true
                  example: 1732289380
      responses:
        '200':
          description: Campaña modificada exitosamente.
          content:
            application/json:
              schema:
                type: object
                properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: "event2026"
                    links:
                      type: array
                      items:
                        type: string
                        example: "abcdef"
                    created_at:
                      type: integer
                      example: 1732289376
                    modified_at:
                      type: integer
                      nullable: true
                      example: 1732289376
                    ends_at:
                      type: integer
                      nullable: true
                      example: 1732289376
        '401':
          description: No hay una sesión activa.
        '404':
          description: La campaña especificada no existe.
    
    delete:
      tags:
        - Campaigns
      summary: Eliminar una campaña
      description: Permite eliminar una campaña existente utilizando su nombre único. Esta operación es irreversible.
      responses:
        '204':
          description: Campaña eliminada exitosamente.
        '401':
          description: No hay una sesión activa.
        '404':
          description: La campaña especificada no existe.