Streamline simple repository API specification

source/specifications/simple-repository-api.openapi.yml

@@ -0,0 +1,202 @@
+openapi: '3.1.0'
+
+info:
+  title: Simple Repository API
+  version: '1.1'
+  summary: A protocol for tools to list and and download Python packages
+  license:
+    name: Creative Commons Attribution-ShareAlike
+    url: https://creativecommons.org/licenses/by-sa/3.0
+
+paths:
+  /:
+    get:
+      summary: Projects list
+      description: List all projects provided by this package index
+      responses:
+        200:
+          description: Success
+          content:
+            text/html:
+              schema:
+                title: HTML response
+                type: string
+            application/vnd.pypi.simple.v1+html:
+              schema:
+                title: HTML response
+                type: string
+            application/vnd.pypi.simple.v1+json:
+              schema:
+                title: JSON response
+                type: object
+                required:
+                  - meta
+                  - projects
+                properties:
+                  meta:
+                    $ref: '#/components/schemas/meta'
+                  projects:
+                    title: Projects list
+                    type: array
+                    items:
+                      title: Project reference
+                      type: object
+                      required:
+                        - name
+                      properties:
+                        name:
+                          title: Project name
+                          type: string
+              example:
+                meta:
+                  api-version: '1.0'
+                projects:
+                  - name: Frob
+                  - name: spamspamspam
+
+  /{project}/:
+    parameters:
+      - name: project
+        in: path
+        description: Project normalised name
+        required: true
+        example: numpy
+        schema:
+          type: string
+          pattern: ^[a-z0-9](-?[a-z0-9])*[a-z0-9]?$
+
+    get:
+      summary: Project details
+      description: Some project details and all package files in the index for
+        the project
+      responses:
+        200:
+          description: Success
+          content:
+            text/html:
+              schema:
+                title: HTML response
+                type: string
+            application/vnd.pypi.simple.v1+html:
+              schema:
+                title: HTML response
+                type: string
+            application/vnd.pypi.simple.v1+json:
+              schema:
+                title: JSON response
+                type: object
+                required:
+                  - meta
+                  - name
+                  - files
+                properties:
+                  meta:
+                    $ref: '#/components/schemas/meta'
+                  name:
+                    title: Project name (normalised)
+                    type: string
+                    pattern: ^[a-z0-9](-?[a-z0-9])*[a-z0-9]?$
+                  files:
+                    title: Project package files
+                    type: array
+                    items:
+                      title: Package file details
+                      type: object
+                      required:
+                        - filename
+                        - url
+                        - hashes
+                      properties:
+                        filename:
+                          title: Package filename
+                          type: string
+                        url:
+                          title: File download URL
+                          type: string
+                          format: uri-reference
+                        hashes:
+                          $ref: '#/components/schemas/hashes'
+                        requires-python:
+                          title: Python requirement
+                          description: Value of distribution's
+                            `Requires-Python` metadata field
+                          type: string
+                        dist-info-metadata:
+                          title: Distribution metadata file details
+                          description: Indicates whether the distribution
+                            metadata file exists. This file is located at the
+                            URL equal to the package file's URL appended with
+                            `.metadata`
+                          oneOf:
+                            - title: Metadata file existence
+                              type: boolean
+                            - $ref: '#/components/schemas/hashes'
+                        gpg-sig:
+                          title: File GPG signature file existence
+                          description: Indicates whether the GPG signature
+                            file exists. This file is located at the URL equal
+                            to the package file's URL appended with `.asc`
+                          type: boolean
+                        yanked:
+                          title: Distribution yanked details
+                          description: Indicates whether the distribution has
+                            been yanked
+                          oneOf:
+                            - title: Yanked status
+                              type: boolean
+                            - title: Yanked reason
+                              type: string
+              example:
+                meta:
+                  api-version: '1.0'
+                name: holygrail
+                files:
+                  - filename: holygrail-1.0.tar.gz
+                    url: https://example.com/files/holygrail-1.0.tar.gz
+                    hashes:
+                      sha256: ...
+                      blake2b: ...
+                    requires-python: '>=3.7'
+                    yanked: Had a vulnerability
+                  - filename: holygrail-1.0-py3-none-any.whl
+                    url: https://example.com/files/holygrail-1.0-py3-none-any.whl
+                    hashes:
+                      sha256: ...
+                      blake2b: ...
+                    requires-python: '>=3.7'
+                    dist-info-metadata: true
+
+        404:
+          description: Project not known by the index
+
+components:
+  schemas:
+    meta:
+      title: Response meta-details
+      type: object
+      properties:
+        api-version:
+          type: string
+          enum: ['1.0', '1.1', '1.2']
+
+    hashes:
+      title: File hashes
+      type: object
+      additionalProperties:
+        title: Hash value
+        description: Hexadecimal encoding of hash value
+        type: string
+        pattern: ^[0-9a-f]+$
+      propertyNames:
+        title: Hash name
+        description: Name of hash algorithm in `hashlib`, lower-case,
+          preferably `sha256`
+        pattern: ^[a-z0-9_]+$
+      examples:
+        - sha256: 4e388ab32b10dc8dbc7e28144f552830adc74787c1e2c0824032078a79f227fb
+
+servers:
+  - url: https://pypi.org/simple/
+    description: PyPI, the default package index used by most Python packaging
+      tools. It runs [Warehouse](https://warehouse.pypa.io/) as the index
+      server.