Update DVP Data API spec

docker-hub/api/dvp.yaml

@@ -18,7 +18,7 @@ info:
      - Tag- or digest-level, a summary of every namespace, repository, and reference
        (tag or digest)
 
-      The summary data formats contain the following data points:
+     The summary data formats contain the following data points:
 
      - Unique IP address count
      - Pulls by tag count
@@ -180,6 +180,23 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NamespaceData'
+  /namespaces:
+    get:
+      tags: [discovery]
+      summary: Get user's namespaces
+      description: Get metadata associated with the namespaces the user has access to, including extra repos associated with the namespaces
+      operationId: getUserNamespaces
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NamespaceMetadata'
+        '401':
+          description: Authentication failed or second factor required
   /namespaces/{namespace}:
     get:
       tags: [discovery]
@@ -200,6 +217,92 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/NamespaceMetadata'
+  /namespaces/{namespace}/pulls:
+    get:
+      tags: [namespaces]
+      summary: Get pull data
+      description: Gets pull for the given namespace
+      operationId: getNamespacePulls
+      parameters:
+        - in: path
+          name: namespace
+          schema:
+            type: string
+          required: true
+          description: Namespace to fetch data for
+        - in: query
+          name: timespan
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: false
+          description: Timespan type for fetching data
+        - in: query
+          name: period
+          schema:
+            $ref: '#/components/schemas/PeriodType'
+          required: false
+          description: Relative period of the period to fetch data
+        - in: query
+          name: group
+          schema:
+            $ref: '#/components/schemas/GroupType'
+          required: false
+          description: Field to group the data by
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PullData'
+        '404':
+          description: Not found - namespace doesn't exist or user does not have permission to access it
+  /namespaces/{namespace}/repos/{repo}/pulls:
+    get:
+      tags: [namespaces]
+      summary: Get pull data
+      description: Gets pull for the given repo
+      operationId: getRepoPulls
+      parameters:
+        - in: path
+          name: namespace
+          schema:
+            type: string
+          required: true
+          description: Namespace to fetch data for
+        - in: path
+          name: repo
+          schema:
+            type: string
+          required: true
+          description: Repository to fetch data for
+        - in: query
+          name: timespan
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: false
+          description: Timespan type for fetching data
+        - in: query
+          name: period
+          schema:
+            $ref: '#/components/schemas/PeriodType'
+          required: false
+          description: Relative period of the period to fetch data
+        - in: query
+          name: group
+          schema:
+            $ref: '#/components/schemas/GroupType'
+          required: false
+          description: Field to group the data by
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PullData'
+        '404':
+          description: Not found - repo doesn't exist or user does not have permission to access it
   /namespaces/{namespace}/pulls/exports/years:
     get:
       tags: [namespaces]
@@ -336,6 +439,46 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ResponseData'
+  /repos/pulls:
+    get:
+      tags: [namespaces]
+      summary: Get pull data for multiple repos
+      description: Gets pull for the given repos
+      operationId: getManyReposPulls
+      parameters:
+        - in: query
+          name: repos
+          schema:
+            type: array
+            items:
+              type: string
+          required: true
+          description: Repositories to fetch data for (maximum of 50 repositories per request).
+        - in: query
+          name: timespan
+          schema:
+            $ref: '#/components/schemas/TimespanType'
+          required: false
+          description: Timespan type for fetching data
+        - in: query
+          name: period
+          schema:
+            $ref: '#/components/schemas/PeriodType'
+          required: false
+          description: Relative period of the period to fetch data
+        - in: query
+          name: group
+          schema:
+            $ref: '#/components/schemas/GroupType'
+          required: false
+          description: Field to group the data by
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReposPullData'
 
 components:
   schemas:
@@ -457,6 +600,35 @@ components:
           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:
@@ -490,9 +662,12 @@ components:
     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]
+      enum: [raw,summary,repo-summary,namespace-summary]
     DatasetType:
       type: string
       enum: [pulls]
@@ -504,6 +679,9 @@ components:
       oneOf:
         - $ref: '#/components/schemas/MonthData'
         - $ref: '#/components/schemas/WeekData'
+    GroupType:
+      type: string
+      enum: [repo,namespace]
   securitySchemes:
     HubAuth:
       type: https
@@ -512,7 +690,5 @@ components:
       description: |
         JWT Bearer Authentication is required to access the Docker DVP Data API.  
           
-        Note - PATs are not supported on this API  
-          
         This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/docker-hub/api/latest/#tag/authentication)
       x-displayName: Docker Hub Authentication