[docker-hub-api] add list namespace repositories endpoint

vdamery · vdamery · commit 42a7b452f282 · 2025-06-27T11:58:25.000+02:00
diff --git a/content/reference/api/hub/latest-changelog.md b/content/reference/api/hub/latest-changelog.md
@@ -11,6 +11,13 @@ toc_max: 2
 Here you can learn about the latest changes, new features, bug fixes, and known
 issues for Docker Service APIs.
 
+## 2025-06-27
+
+### New
+
+- Add [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories) endpoints for a given `namespace`.
+- Deprecate undocumented endpoint `GET /v2/repositories/{namespace}` replaced by [List repositories](/reference/api/hub/latest/#tag/repositories/operation/listNamespaceRepositories).
+
 ## 2025-03-25
 
 ### New
diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml
@@ -926,8 +926,152 @@ paths:
           $ref: "#/components/responses/forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
+  /v2/namespaces/{namespace}/repositories:
+    parameters:
+      - $ref: "#/components/parameters/namespace"
+    get:
+      operationId: listNamespaceRepositories
+      summary: List repositories in a namespace
+      description: |
+        Returns a list of repositories within the specified namespace (organization or user).
+        
+        Public repositories are accessible to everyone, while private repositories require appropriate authentication and permissions.
+      tags:
+        - repositories
+      security:
+        - bearerAuth: [ ]
+        - { }  # Allow anonymous access for public repositories
+      parameters:
+        - in: query
+          name: page
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+          description: Page number to get. Defaults to 1.
+        - in: query
+          name: page_size
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 1000
+            default: 10
+          description: Number of repositories to get per page. Defaults to 10. Max of 1000.
+        - in: query
+          name: name
+          required: false
+          schema:
+            type: string
+          description: Filter repositories by name (partial match).
+        - in: query
+          name: ordering
+          required: false
+          schema:
+            type: string
+            enum:
+              - name
+              - -name
+              - last_updated
+              - -last_updated
+              - pull_count
+              - -pull_count
+          description: |
+            Order repositories by the specified field. Prefix with '-' for descending order.
+            Available options:
+            - `name` / `-name`: Repository name (ascending/descending)
+            - `last_updated` / `-last_updated`: Last update time (ascending/descending)
+            - `pull_count` / `-pull_count`: Number of pulls (ascending/descending)
+      responses:
+        "200":
+          description: List of repositories
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/list_repositories_response"
+              examples:
+                repositories_list:
+                  value:
+                    count: 287
+                    next: "https://hub.docker.com/v2/namespaces/docker/repositories?page=2&page_size=2"
+                    previous: null
+                    results:
+                      - name: "highland_builder"
+                        namespace: "docker"
+                        repository_type: "image"
+                        status: 1
+                        status_description: "active"
+                        description: "Image for performing Docker build requests"
+                        is_private: false
+                        star_count: 7
+                        pull_count: 15722123
+                        last_updated: "2023-06-20T10:44:45.459826Z"
+                        last_modified: "2024-10-16T13:48:34.145251Z"
+                        date_registered: "2015-05-19T21:13:35.937763Z"
+                        affiliation: ""
+                        media_types:
+                          - "application/octet-stream"
+                          - "application/vnd.docker.container.image.v1+json"
+                          - "application/vnd.docker.distribution.manifest.v1+prettyjws"
+                        content_types:
+                          - "unrecognized"
+                          - "image"
+                        categories:
+                          - name: "Languages & frameworks"
+                            slug: "languages-and-frameworks"
+                          - name: "Integration & delivery"
+                            slug: "integration-and-delivery"
+                          - name: "Operating systems"
+                            slug: "operating-systems"
+                        storage_size: 488723114800
+                      - name: "whalesay"
+                        namespace: "docker"
+                        repository_type: null
+                        status: 1
+                        status_description: "active"
+                        description: "An image for use in the Docker demo tutorial"
+                        is_private: false
+                        star_count: 757
+                        pull_count: 130737682
+                        last_updated: "2015-06-19T19:06:27.388123Z"
+                        last_modified: "2024-10-16T13:48:34.145251Z"
+                        date_registered: "2015-06-09T18:16:36.527329Z"
+                        affiliation: ""
+                        media_types:
+                          - "application/vnd.docker.distribution.manifest.v1+prettyjws"
+                        content_types:
+                          - "image"
+                        categories:
+                          - name: "Languages & frameworks"
+                            slug: "languages-and-frameworks"
+                          - name: "Integration & delivery"
+                            slug: "integration-and-delivery"
+                        storage_size: 103666708
+        "400":
+          description: Bad Request - Invalid request parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
+              examples:
+                invalid_ordering:
+                  summary: Invalid ordering value
+                  value:
+                    fields:
+                      ordering: [ "Invalid ordering value. Must be one of: name, -name, last_updated, -last_updated, pull_count, -pull_count" ]
+                    text: "Invalid ordering value"
+        "401":
+          $ref: "#/components/responses/unauthorized"
+        "403":
+          $ref: "#/components/responses/forbidden"
+        "404":
+          description: Page not found - occurs when requesting a page number `>1` that exceeds the available results
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/error"
 
-          
   /v2/orgs/{org_name}/members:
     parameters:
       - $ref: "#/components/parameters/org_name"
@@ -2009,6 +2153,129 @@ components:
           schema:
             $ref: "#/components/schemas/scim_user"
   schemas:
+    repository_list_entry:
+      type: object
+      properties:
+        name:
+          type: string
+          description: Name of the repository
+          example: "hello-world"
+        namespace:
+          type: string
+          description: Namespace (organization or username) that owns the repository
+          example: "docker"
+        repository_type:
+          type: string
+          description: Type of repository
+          enum:
+            - image
+            - plugin
+            - null
+          example: "image"
+          nullable: true
+        status:
+          type: integer
+          description: Repository status code
+          example: 1
+        status_description:
+          type: string
+          description: Human-readable repository status
+          enum:
+            - active
+            - inactive
+          example: "active"
+        description:
+          type: string
+          description: Repository description
+          nullable: true
+          example: "Hello World! (an example of minimal Dockerization)"
+        is_private:
+          type: boolean
+          description: Whether the repository is private
+          example: false
+        star_count:
+          type: integer
+          description: Number of users who starred this repository
+          minimum: 0
+          example: 1234
+        pull_count:
+          type: integer
+          description: Total number of pulls for this repository
+          minimum: 0
+          example: 50000000
+        last_updated:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the repository was last updated
+          example: "2023-12-01T10:30:00Z"
+          nullable: true
+        last_modified:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the repository was last modified
+          example: "2023-12-01T10:30:00Z"
+          nullable: true
+        date_registered:
+          type: string
+          format: date-time
+          description: ISO 8601 timestamp of when the repository was created
+          example: "2013-06-19T19:07:54Z"
+        affiliation:
+          type: string
+          description: User's affiliation with the repository (empty string if no affiliation)
+          example: ""
+        media_types:
+          type: array
+          description: Media types supported by this repository
+          items:
+            type: string
+          example:
+            - "application/vnd.docker.plugin.v1+json"
+        content_types:
+          type: array
+          description: Content types supported by this repository
+          items:
+            type: string
+          example:
+            - "plugin"
+        categories:
+          type: array
+          description: Categories associated with this repository
+          items:
+            $ref: "#/components/schemas/category"
+          example: []
+        storage_size:
+          type: integer
+          description: Storage size in bytes used by this repository
+          minimum: 0
+          example: 232719127
+    category:
+      type: object
+      required:
+        - name
+        - slug
+      properties:
+        name:
+          type: string
+          description: Human-readable name of the category
+          example: "Databases"
+          minLength: 1
+        slug:
+          type: string
+          description: URL-friendly identifier for the category
+          example: "databases"
+          minLength: 1
+          pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      description: Repository category for classification and discovery
+    list_repositories_response:
+      allOf:
+        - $ref: "#/components/schemas/page"
+        - type: object
+          properties:
+            results:
+              type: array
+              items:
+                $ref: "#/components/schemas/repository_list_entry"
     UsersLoginRequest:
       description: User login details
       type: object
