movieapp-openapi-spec

movieapp.yaml

openapi: 3.0.0
info:
  title: MovieApp API
  description: API para una aplicación de películas con autenticación basada en JWT y autorización mediante scopes, siguiendo principios de DDD.
  version: 1.0.0
servers:
  - url: https://api.movieapp.com/v1
    description: Servidor de Producción
  - url: http://localhost:8080/v1
    description: Servidor de Desarrollo Local

tags:
  - name: Identity
    description: Operaciones relacionadas con la identidad y autenticación de usuarios
  - name: Catalog
    description: Operaciones relacionadas con el catálogo de películas, actores y categorías
  - name: Social Interaction
    description: Operaciones relacionadas con la interacción social, como seguir usuarios y calificar películas

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # Value Objects
    Email:
      type: string
      format: email
      description: Dirección de correo electrónico válida

    Password:
      type: string
      format: password
      description: Contraseña del usuario
      minLength: 8

    Username:
      type: string
      description: Nombre de usuario único
      minLength: 3

    Name:
      type: string
      description: Nombre o apellido
      minLength: 1

    Gender:
      type: string
      enum: [male, female, other]
      description: Género del usuario

    Date:
      type: string
      format: date
      description: Fecha en formato ISO 8601

    UUID:
      type: string
      format: uuid
      description: Identificador Único Universal

    Scope:
      type: string
      enum: [none, read, write, admin]
      description: Nivel de permiso del usuario

    # Aggregates and Entities
    User:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        username:
          $ref: '#/components/schemas/Username'
        email:
          $ref: '#/components/schemas/Email'
        firstName:
          $ref: '#/components/schemas/Name'
        lastName:
          $ref: '#/components/schemas/Name'
        avatar:
          type: string
          format: uri
          description: URL de la foto de perfil del usuario
        birthdate:
          $ref: '#/components/schemas/Date'
        gender:
          $ref: '#/components/schemas/Gender'
        scope:
          $ref: '#/components/schemas/Scope'
      required:
        - id
        - username
        - email
        - scope

    UserRegistration:
      type: object
      properties:
        username:
          $ref: '#/components/schemas/Username'
        email:
          $ref: '#/components/schemas/Email'
        password:
          $ref: '#/components/schemas/Password'
        firstName:
          $ref: '#/components/schemas/Name'
        lastName:
          $ref: '#/components/schemas/Name'
        avatar:
          type: string
          format: uri
          description: URL de la foto de perfil del usuario
        birthdate:
          $ref: '#/components/schemas/Date'
        gender:
          $ref: '#/components/schemas/Gender'
      required:
        - username
        - email
        - password

    UserProfileUpdate:
      type: object
      properties:
        firstName:
          $ref: '#/components/schemas/Name'
        lastName:
          $ref: '#/components/schemas/Name'
        avatar:
          type: string
          format: uri
          description: URL de la foto de perfil del usuario
        birthdate:
          $ref: '#/components/schemas/Date'
        gender:
          $ref: '#/components/schemas/Gender'

    Movie:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        title:
          type: string
          description: Título de la película
        description:
          type: string
          description: Descripción de la película
        releaseDate:
          $ref: '#/components/schemas/Date'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: Lista de categorías asociadas
        actors:
          type: array
          items:
            $ref: '#/components/schemas/Actor'
          description: Lista de actores asociados
      required:
        - id
        - title

    MovieCreate:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        releaseDate:
          $ref: '#/components/schemas/Date'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Lista de IDs de categorías
        actors:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Lista de IDs de actores
      required:
        - title

    Category:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        name:
          type: string
          description: Nombre de la categoría
        description:
          type: string
          description: Descripción de la categoría
      required:
        - id
        - name

    Actor:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        firstName:
          $ref: '#/components/schemas/Name'
        lastName:
          $ref: '#/components/schemas/Name'
        birthdate:
          $ref: '#/components/schemas/Date'
        gender:
          $ref: '#/components/schemas/Gender'
        biography:
          type: string
          description: Biografía del actor
      required:
        - id
        - firstName
        - lastName

    Rating:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/UUID'
        userId:
          $ref: '#/components/schemas/UUID'
        movieId:
          $ref: '#/components/schemas/UUID'
        rating:
          type: integer
          minimum: 1
          maximum: 10
          description: Puntuación otorgada
        timestamp:
          type: string
          format: date-time
          description: Fecha y hora de la calificación
      required:
        - id
        - userId
        - movieId
        - rating
        - timestamp

  parameters:
    UserId:
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: ID del usuario

    MovieId:
      name: movieId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: ID de la película

    CategoryId:
      name: categoryId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: ID de la categoría

    ActorId:
      name: actorId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
      description: ID del actor

paths:
  # Identity Bounded Context
  /users/register:
    post:
      tags:
        - Identity
      summary: Registrar un nuevo usuario (scope=none)
      description: Registrar un nuevo usuario en el sistema.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistration'
      responses:
        '201':
          description: Usuario registrado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Solicitud incorrecta (e.g., campos requeridos faltantes)
        '409':
          description: Conflicto (e.g., el correo electrónico o nombre de usuario ya existe)

  /users/login:
    post:
      tags:
        - Identity
      summary: Inicio de sesión de usuario (scope=none)
      description: Iniciar sesión utilizando Authorization Basic
      security:
        - BasicAuth: []
      responses:
        '200':
          description: Inicio de sesión exitoso
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
        '401':
          description: No autorizado (e.g., credenciales inválidas)

  /users/{userId}:
    get:
      tags:
        - Identity
      summary: Obtener perfil de usuario (scope=read)
      description: Recuperar la información del perfil de un usuario específico.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Perfil de usuario obtenido exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: No autorizado (e.g., token inválido)
        '404':
          description: Usuario no encontrado

    put:
      tags:
        - Identity
      summary: Actualizar perfil de usuario (scope=write)
      description: Actualizar la información del perfil del usuario autenticado.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfileUpdate'
      responses:
        '200':
          description: Perfil de usuario actualizado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (no puede actualizar el perfil de otro usuario)
        '404':
          description: Usuario no encontrado

    delete:
      tags:
        - Identity
      summary: Eliminar cuenta de usuario (scope=write/admin)
      description: Eliminar la cuenta del usuario autenticado (scope=write) o eliminar cualquier cuenta (scope=admin).
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: Cuenta de usuario eliminada exitosamente
        '401':
          description: No autorizado
        '403':
          description: Prohibido (no tiene permisos para eliminar esta cuenta)
        '404':
          description: Usuario no encontrado

  # Catalog Bounded Context
  /movies:
    get:
      tags:
        - Catalog
      summary: Buscar películas recomendadas (scope=none)
      description: Buscar películas con filtros opcionales por título, actor o categoría.
      parameters:
        - name: title
          in: query
          schema:
            type: string
          description: Filtrar por título de la película
        - name: actor
          in: query
          schema:
            type: string
          description: Filtrar por nombre del actor
        - name: category
          in: query
          schema:
            type: string
          description: Filtrar por nombre de la categoría
      responses:
        '200':
          description: Lista de películas
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Movie'
        '400':
          description: Solicitud incorrecta

    post:
      tags:
        - Catalog
      summary: Crear una nueva película (scope=admin)
      description: Crear una nueva película en el catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovieCreate'
      responses:
        '201':
          description: Película creada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)

  /movies/{movieId}:
    get:
      tags:
        - Catalog
      summary: Obtener detalles de una película (scope=none)
      description: Obtener información detallada de una película específica.
      parameters:
        - $ref: '#/components/parameters/MovieId'
      responses:
        '200':
          description: Detalles de la película obtenidos exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
        '404':
          description: Película no encontrada

    put:
      tags:
        - Catalog
      summary: Actualizar una película (scope=admin)
      description: Actualizar la información de una película existente. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/MovieId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MovieCreate'
      responses:
        '200':
          description: Película actualizada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Película no encontrada

    delete:
      tags:
        - Catalog
      summary: Eliminar una película (scope=admin)
      description: Eliminar una película del catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/MovieId'
      responses:
        '204':
          description: Película eliminada exitosamente
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Película no encontrada

  /categories:
    get:
      tags:
        - Catalog
      summary: Obtener lista de categorías (scope=none)
      description: Recuperar una lista de todas las categorías disponibles.
      responses:
        '200':
          description: Lista de categorías
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '400':
          description: Solicitud incorrecta

    post:
      tags:
        - Catalog
      summary: Crear una nueva categoría (scope=admin)
      description: Crear una nueva categoría en el catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '201':
          description: Categoría creada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)

  /categories/{categoryId}:
    put:
      tags:
        - Catalog
      summary: Actualizar una categoría (scope=admin)
      description: Actualizar información de una categoría existente. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CategoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '200':
          description: Categoría actualizada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Categoría no encontrada

    delete:
      tags:
        - Catalog
      summary: Eliminar una categoría (scope=admin)
      description: Eliminar una categoría del catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CategoryId'
      responses:
        '204':
          description: Categoría eliminada exitosamente
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Categoría no encontrada

  /actors:
    get:
      tags:
        - Catalog
      summary: Obtener lista de actores (scope=none)
      description: Recuperar una lista de todos los actores disponibles.
      responses:
        '200':
          description: Lista de actores
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Actor'
        '400':
          description: Solicitud incorrecta

    post:
      tags:
        - Catalog
      summary: Crear un nuevo actor (scope=admin)
      description: Crear un nuevo actor en el catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Actor'
      responses:
        '201':
          description: Actor creado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Actor'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)

  /actors/{actorId}:
    put:
      tags:
        - Catalog
      summary: Actualizar un actor (scope=admin)
      description: Actualizar información de un actor existente. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ActorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Actor'
      responses:
        '200':
          description: Actor actualizado exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Actor'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Actor no encontrado

    delete:
      tags:
        - Catalog
      summary: Eliminar un actor (scope=admin)
      description: Eliminar un actor del catálogo. Requiere rol ADMIN.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ActorId'
      responses:
        '204':
          description: Actor eliminado exitosamente
        '401':
          description: No autorizado
        '403':
          description: Prohibido (requiere rol ADMIN)
        '404':
          description: Actor no encontrado

  # Social Interaction Bounded Context
  /movies/{movieId}/ratings:
    post:
      tags:
        - Social Interaction
      summary: Calificar una película (scope=write)
      description: Permite al usuario autenticado calificar una película con una puntuación de 1 a 10.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/MovieId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rating:
                  type: integer
                  minimum: 1
                  maximum: 10
                  description: Puntuación otorgada
              required:
                - rating
      responses:
        '201':
          description: Película calificada exitosamente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rating'
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '404':
          description: Película no encontrada

    get:
      tags:
        - Social Interaction
      summary: Obtener calificaciones de una película (scope=none)
      description: Recuperar las calificaciones que otros usuarios han dado a una película.
      parameters:
        - $ref: '#/components/parameters/MovieId'
      responses:
        '200':
          description: Lista de calificaciones
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Rating'
        '404':
          description: Película no encontrada

  /users:
    get:
      tags:
        - Social Interaction
      summary: Buscar otros usuarios (scope=read)
      description: Buscar usuarios en la plataforma por correo electrónico, nombre o nombre de usuario.
      security:
        - BearerAuth: []
      parameters:
        - name: email
          in: query
          schema:
            type: string
          description: Filtrar por correo electrónico
        - name: name
          in: query
          schema:
            type: string
          description: Filtrar por nombre
        - name: username
          in: query
          schema:
            type: string
          description: Filtrar por nombre de usuario
      responses:
        '200':
          description: Lista de usuarios
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: No autorizado
        '400':
          description: Solicitud incorrecta

  /users/{userId}/follow:
    post:
      tags:
        - Social Interaction
      summary: Enviar solicitud de seguimiento a un usuario (scope=write)
      description: Enviar una solicitud para seguir a otro usuario.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Solicitud de seguimiento enviada exitosamente
        '401':
          description: No autorizado
        '404':
          description: Usuario no encontrado
        '409':
          description: Conflicto (ya se envió una solicitud o ya sigue al usuario)

  /users/{userId}/followers:
    get:
      tags:
        - Social Interaction
      summary: Obtener lista de seguidores del usuario (scope=read)
      description: Recuperar la lista de usuarios que siguen al usuario especificado.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Lista de seguidores
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: No autorizado
        '404':
          description: Usuario no encontrado

  /users/{userId}/following:
    get:
      tags:
        - Social Interaction
      summary: Obtener lista de usuarios seguidos (scope=read)
      description: Recuperar la lista de usuarios que el usuario especificado está siguiendo.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Lista de usuarios seguidos
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: No autorizado
        '404':
          description: Usuario no encontrado

  /users/{userId}/follow-requests:
    get:
      tags:
        - Social Interaction
      summary: Obtener solicitudes de seguimiento pendientes (scope=read)
      description: Obtener las solicitudes de seguimiento que el usuario ha recibido y aún no ha aceptado o rechazado.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Lista de solicitudes de seguimiento pendientes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: No autorizado
        '404':
          description: Usuario no encontrado

  /users/{userId}/follow-requests/{requesterId}:
    post:
      tags:
        - Social Interaction
      summary: Aceptar o rechazar una solicitud de seguimiento (scope=write)
      description: Procesar una solicitud de seguimiento aceptándola o rechazándola.
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: requesterId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/UUID'
          description: ID del usuario que envió la solicitud
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum: [accept, reject]
              required:
                - action
      responses:
        '200':
          description: Solicitud de seguimiento procesada exitosamente
        '400':
          description: Solicitud incorrecta
        '401':
          description: No autorizado
        '404':
          description: Usuario o solicitud no encontrada