openapi: 3.0.0
info:
  title: API de datos de DVP
  version: 1.0.0
  x-logo:
    url: https://docs-docker.esdocu.com/assets/images/logo-docker-main.png
    href: /reference
  description: |
    La API de datos DVP de Docker permite a los [Docker Verified Publishers](https://docs-docker.esdocu.com/docker-hub/publish/) ver los datos analíticos de descargas (pulls) de imágenes para sus espacios de nombres. Los datos analíticos se pueden obtener en formato CSV como datos brutos, o en formato resumido.
      
    #### Datos resumidos

    En el CSV de datos resumidos, tendrás acceso a los puntos de datos indicados a continuación. Puedes solicitar datos resumidos para una semana completa (de lunes a domingo) o para un mes completo (disponible el primer día del mes siguiente). 

    Existen dos niveles de datos resumidos:

    - A nivel de repositorio: un resumen de cada espacio de nombres y repositorio.
    - A nivel de etiqueta o digest: un resumen de cada espacio de nombres, repositorio y referencia (etiqueta o digest).

    Los formatos de datos resumidos contienen los siguientes puntos de datos:

    - Recuento de direcciones IP únicas
    - Recuento de descargas (pulls) por etiqueta
    - Recuento de descargas (pulls) por digest
    - Recuento de comprobaciones de versión

    #### Datos brutos

    En el CSV de datos brutos, tendrás acceso a los puntos de datos indicados a continuación. Puedes solicitar datos brutos para una semana completa (de lunes a domingo) o para un mes completo (disponible el primer día del mes siguiente). **Nota:** cada acción se representa como una única fila.

    - Tipo (industria)
    - Host (proveedor de la nube)
    - País (geolocalización)
    - Marca de tiempo (Timestamp)
    - Espacio de nombres (Namespace)
    - Repositorio
    - Referencia (el digest siempre está incluido, la etiqueta se proporciona cuando está disponible)
    - Método de petición HTTP
    - Acción, una de las siguientes:
      - Descarga por etiqueta (Pull by tag)
      - Descarga por digest (Pull by digest)
      - Comprobación de versión (Version check)
    - Agente de usuario (User-Agent)

servers:
  - url: https://hub.docker.com/api/publisher/analytics/v1
security:
  - HubAuth: []

features.openapi:
  schemaDefinitionsTagName: Schemas

tags:
  - name: authentication
    x-displayName: Puntos de conexión de autenticación
  - name: namespaces
    x-displayName: Datos de espacio de nombres
  - name: discovery
    x-displayName: Descubrimiento
  - name: responseDataFile
    x-displayName: ResponseDataFile
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/ResponseDataFile" />
  - name: yearModel
    x-displayName: Modelo de datos anual
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/YearModel" />
  - name: monthModel
    x-displayName: Modelo de datos mensual
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/MonthModel" />
  - name: weekModel
    x-displayName: Modelo de datos semanal
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/WeekModel" />

x-tagGroups:
  - name: API
    tags:
      - authentication
      - discovery
      - namespaces
  - name: Models
    tags:
      - responseDataFile
      - yearModel
      - monthModel
      - weekModel

paths:
  /v2/users/login:
    security: []
    servers:
      - url: https://hub.docker.com
    post:
      security: []
      tags:
        - authentication
      summary: Crear un token de autenticación
      operationId: PostUsersLogin
      description: |
        Crea y devuelve un token de portador (bearer token) en formato JWT que puedes usar para
        autenticarte en las APIs de Docker Hub.

        El token devuelto se utiliza en la cabecera HTTP Authorization de la forma `Authorization: Bearer {TOKEN}`.

        La mayoría de las APIs de Docker Hub requieren este token ya sea para consumir recursos o para obtener información detallada. Por ejemplo, para listar imágenes en un repositorio privado.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsersLoginRequest"
        description: Detalles de inicio de sesión.
        required: true
      responses:
        200:
          description: Autenticación exitosa
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
        401:
          description: Autenticación fallida o se requiere un segundo factor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostUsersLoginErrorResponse"
  /v2/users/2fa-login:
    security: []
    servers:
      - url: https://hub.docker.com
    post:
      security: []
      tags:
        - authentication
      summary: Autenticación de segundo factor
      operationId: PostUsers2FALogin
      description: |
        Cuando un usuario tiene habilitado el doble factor de autenticación (2FA), esta es la segunda llamada que se debe realizar después de
        la llamada a `/v2/users/login`.

        Crea y devuelve un token de portador (bearer token) en formato JWT que puedes utilizar para autenticarte en las APIs de Docker Hub.

        El token devuelto se utiliza en la cabecera HTTP Authorization de la forma `Authorization: Bearer {TOKEN}`.

        La mayoría de las APIs de Docker Hub requieren este token ya sea para consumir recursos o para obtener información detallada. Por ejemplo, para listar imágenes en un repositorio privado.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Users2FALoginRequest"
        description: Detalles de inicio de sesión.
        required: true
      responses:
        200:
          description: Autenticación exitosa
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostUsersLoginSuccessResponse"
        401:
          description: Autenticación fallida o se requiere un segundo factor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostUsers2FALoginErrorResponse"

  /:
    get:
      tags: [discovery]
      summary: Obtener espacios de nombres y repositorios
      description: Obtiene una lista de tus espacios de nombres y repositorios que tienen datos disponibles.
      operationId: getNamespaces
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NamespaceData"
  /namespaces:
    get:
      tags: [discovery]
      summary: Obtener los espacios de nombres del usuario
      description: Obtiene los metadatos asociados con los espacios de nombres a los que tiene acceso el usuario, incluidos los repositorios adicionales asociados a los mismos.
      operationId: getUserNamespaces
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NamespaceMetadata"
        "401":
          description: Autenticación fallida o se requiere un segundo factor
  /namespaces/{namespace}:
    get:
      tags: [discovery]
      summary: Obtener espacio de nombres
      description: Obtiene los metadatos asociados con el espacio de nombres especificado, incluidos los repositorios adicionales asociados al mismo.
      operationId: getNamespace
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NamespaceMetadata"
  /namespaces/{namespace}/pulls:
    get:
      tags: [namespaces]
      summary: Obtener datos de descargas (pulls)
      description: Obtiene las descargas (pulls) para el espacio de nombres dado.
      operationId: getNamespacePulls
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
        - in: query
          name: timespan
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: false
          description: Tipo de intervalo de tiempo para obtener los datos
        - in: query
          name: period
          schema:
            $ref: "#/components/schemas/PeriodType"
          required: false
          description: Periodo relativo del periodo para obtener los datos
        - in: query
          name: group
          schema:
            $ref: "#/components/schemas/GroupType"
          required: false
          description: Campo por el que agrupar los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PullData"
        "404":
          description: "No encontrado: el espacio de nombres no existe o el usuario no tiene permiso para acceder a él"
  /namespaces/{namespace}/repos/{repo}/pulls:
    get:
      tags: [namespaces]
      summary: Obtener datos de descargas (pulls)
      description: Obtiene las descargas (pulls) para el repositorio dado.
      operationId: getRepoPulls
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
        - in: path
          name: repo
          schema:
            type: string
          required: true
          description: Repositorio para el que obtener los datos
        - in: query
          name: timespan
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: false
          description: Tipo de intervalo de tiempo para obtener los datos
        - in: query
          name: period
          schema:
            $ref: "#/components/schemas/PeriodType"
          required: false
          description: Periodo relativo del periodo para obtener los datos
        - in: query
          name: group
          schema:
            $ref: "#/components/schemas/GroupType"
          required: false
          description: Campo por el que agrupar los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PullData"
        "404":
          description: "No encontrado: el repositorio no existe o el usuario no tiene permiso para acceder a él"
  /namespaces/{namespace}/pulls/exports/years:
    get:
      tags: [namespaces]
      summary: Obtener años con datos
      description: Obtiene una lista de los años que tienen datos para el espacio de nombres dado.
      operationId: getNamespaceYears
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/YearData"
  /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}:
    get:
      tags: [namespaces]
      summary: Obtener intervalos de tiempo con datos
      description: Obtiene una lista de intervalos de tiempo del tipo dado que tienen datos para el espacio de nombres y año indicados.
      operationId: getNamespaceTimespans
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
        - in: path
          name: year
          schema:
            type: integer
          required: true
          description: Año para el que obtener los datos
        - in: path
          name: timespantype
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: true
          description: Tipo de intervalo de tiempo para el que obtener los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimespanData"
  /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}:
    get:
      tags: [namespaces]
      summary: Obtener metadatos del espacio de nombres para el intervalo de tiempo
      description: Obtiene información sobre los datos para el espacio de nombres e intervalo de tiempo dados.
      operationId: getNamespaceTimespanMetadata
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
        - in: path
          name: year
          schema:
            type: integer
          required: true
          description: Año para el que obtener los datos
        - in: path
          name: timespantype
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: true
          description: Tipo de intervalo de tiempo para el que obtener los datos
        - in: path
          name: timespan
          schema:
            type: integer
          required: true
          description: Intervalo de tiempo para el que obtener los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimespanModel"
        "404":
          description: No encontrado
  /namespaces/{namespace}/pulls/exports/years/{year}/{timespantype}/{timespan}/{dataview}:
    get:
      tags: [namespaces]
      summary: Obtener datos del espacio de nombres para el intervalo de tiempo
      description: Obtiene una lista de URLs que se pueden utilizar para descargar los datos de descargas para el espacio de nombres e intervalo de tiempo dados.
      operationId: getNamespaceDataByTimespan
      parameters:
        - in: path
          name: namespace
          schema:
            type: string
          required: true
          description: Espacio de nombres para el que obtener los datos
        - in: path
          name: year
          schema:
            type: integer
          required: true
          description: Año para el que obtener los datos
        - in: path
          name: timespantype
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: true
          description: Tipo de intervalo de tiempo para el que obtener los datos
        - in: path
          name: timespan
          schema:
            type: integer
          required: true
          description: Intervalo de tiempo para el que obtener los datos
        - in: path
          name: dataview
          schema:
            $ref: "#/components/schemas/DataviewType"
          required: true
          description: Tipo de datos a obtener
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResponseData"
  /repos/pulls:
    get:
      tags: [namespaces]
      summary: Obtener datos de descargas (pulls) para múltiples repositorios
      description: Obtiene las descargas (pulls) para los repositorios dados.
      operationId: getManyReposPulls
      parameters:
        - in: query
          name: repos
          schema:
            type: array
            items:
              type: string
          required: true
          description: Repositorios para los que obtener datos (máximo de 50 repositorios por petición).
        - in: query
          name: timespan
          schema:
            $ref: "#/components/schemas/TimespanType"
          required: false
          description: Tipo de intervalo de tiempo para obtener los datos
        - in: query
          name: period
          schema:
            $ref: "#/components/schemas/PeriodType"
          required: false
          description: Periodo relativo del periodo para obtener los datos
        - in: query
          name: group
          schema:
            $ref: "#/components/schemas/GroupType"
          required: false
          description: Campo por el que agrupar los datos
      responses:
        "200":
          description: Éxito
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReposPullData"

components:
  schemas:
    UsersLoginRequest:
      description: Detalles de inicio de sesión de usuario
      type: object
      required:
        - username
        - password
      properties:
        username:
          description: El nombre de usuario de la cuenta de Docker Hub con la que autenticarse.
          type: string
          example: miusuario
        password:
          description: La contraseña o token de acceso personal (PAT) de la cuenta de Docker Hub con la que autenticarse.
          type: string
          example: hunter2
    PostUsersLoginSuccessResponse:
      description: Respuesta exitosa de inicio de sesión de usuario
      type: object
      properties:
        token:
          description: |
            Token de autenticación creado.

            Este token se puede utilizar en la cabecera HTTP Authorization como un JWT para autenticarse en las APIs de Docker Hub.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          nullable: false
    PostUsersLoginErrorResponse:
      description: Respuesta fallida de inicio de sesión de usuario o se requiere un segundo factor
      type: object
      required:
        - detail
      properties:
        detail:
          description: Descripción del error.
          type: string
          example: Credenciales de autenticación incorrectas
          nullable: false
        login_2fa_token:
          description: Token de corta duración para ser utilizado en `/v2/users/2fa-login` para completar la autenticación. Este campo está presente solo si 2FA está habilitado.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          nullable: true
    Users2FALoginRequest:
      description: Detalles de inicio de sesión del usuario para el segundo factor
      type: object
      required:
        - login_2fa_token
        - code
      properties:
        login_2fa_token:
          description: El token 2FA intermedio devuelto por la API `/v2/users/login`.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        code:
          description: La contraseña de un solo uso basada en el tiempo (TOTP) de la cuenta de Docker Hub con la que autenticarse.
          type: string
          example: 123456
    PostUsers2FALoginErrorResponse:
      description: Respuesta fallida de inicio de sesión del segundo factor.
      type: object
      properties:
        detail:
          description: Descripción del error.
          type: string
          example: Credenciales de autenticación incorrectas
          nullable: false

    ResponseData:
      properties:
        data:
          type: array
          description: |
            Lista de URLs para descargar los datos. Cuando los datos son grandes, se dividirán en múltiples archivos.
          items:
            $ref: "#/components/schemas/ResponseDataFile"
    ResponseDataFile:
      properties:
        url:
          type: string
        size:
          type: integer
          format: int64
    NamespaceData:
      properties:
        namespaces:
          type: array
          items:
            type: string
    NamespaceMetadata:
      properties:
        namespace:
          type: string
        extraRepos:
          type: array
          items:
            type: string
        datasets:
          type: array
          items:
            $ref: "#/components/schemas/DatasetModel"
    DatasetModel:
      properties:
        name:
          $ref: "#/components/schemas/DatasetType"
        views:
          type: array
          items:
            $ref: "#/components/schemas/DataviewType"
        timespans:
          type: array
          items:
            $ref: "#/components/schemas/TimespanType"
    PullData:
      properties:
        pulls:
          type: array
          items:
            $ref: "#/components/schemas/PullModel"
    ReposPullData:
      properties:
        repos:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/PullData"
    PullModel:
      properties:
        start:
          type: string
        end:
          type: string
        repo:
          type: string
        namespace:
          type: string
        pullCount:
          type: integer
        ipCount:
          type: integer
        country:
          type: string

    YearData:
      properties:
        years:
          type: array
          items:
            $ref: "#/components/schemas/YearModel"
    YearModel:
      properties:
        year:
          type: integer
    MonthData:
      properties:
        months:
          type: array
          items:
            $ref: "#/components/schemas/MonthModel"
    MonthModel:
      properties:
        month:
          type: integer
    WeekData:
      properties:
        weeks:
          type: array
          items:
            $ref: "#/components/schemas/WeekModel"
    WeekModel:
      properties:
        week:
          type: integer
    TimespanType:
      type: string
      enum: [months, weeks]
    PeriodType:
      type: string
      enum: [last-2-months, last-3-months, last-6-months, last-12-months]
    DataviewType:
      type: string
      enum: [raw, summary, repo-summary, namespace-summary]
    DatasetType:
      type: string
      enum: [pulls]
    TimespanModel:
      oneOf:
        - $ref: "#/components/schemas/MonthModel"
        - $ref: "#/components/schemas/WeekModel"
    TimespanData:
      oneOf:
        - $ref: "#/components/schemas/MonthData"
        - $ref: "#/components/schemas/WeekData"
    GroupType:
      type: string
      enum: [repo, namespace]
  securitySchemes:
    HubAuth:
      type: https
      scheme: bearer
      bearerFormat: JWT
      description: |
        Se requiere autenticación JWT Bearer para acceder a la API de datos DVP de Docker.

        Esta documentación de autenticación está duplicada de la [documentación de autenticación de la API de Hub](https://docs-docker.esdocu.com/reference/api/hub/#tag/authentication)
      x-displayName: Autenticación de Docker Hub