openapi: 3.0.3
info:
  title: Swift Package Registry API
  description: API for managing Swift package releases and interacting with the package registry.
  version: 1.0.0
tags:
  - name: Releases
  - name: Packages
  - name: Authentication
paths:
  '/{scope}/{name}':
    parameters:
      - $ref: '#/components/parameters/Scope'
      - $ref: '#/components/parameters/PackageName'
    get:
      tags:
        - Releases
      summary: List package releases
      operationId: listPackageReleases
      responses:
        '200':
          description: Retrieve a list of all available releases for a given package
          headers:
            Link:
              $ref: '#/components/headers/PackageLinks'
            Content-Version:
              $ref: '#/components/headers/ContentVersion'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Releases'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  '/{scope}/{name}/{version}':
    parameters:
      - $ref: '#/components/parameters/Scope'
      - $ref: '#/components/parameters/PackageName'
      - $ref: '#/components/parameters/Version'
    get:
      tags:
        - Releases
      summary: Fetch metadata for a package release
      operationId: fetchReleaseMetadata
      responses:
        '200':
          description: Retrieve detailed metadata for a specific package release
          headers:
            Link:
              $ref: '#/components/headers/PackageLinks'
            Content-Version:
              $ref: '#/components/headers/ContentVersion'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/ReleaseMetadata'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      tags:
        - Releases
      summary: Create a package release
      operationId: createPackageRelease
      parameters:
        - in: header
          name: X-Swift-Package-Signature-Format
          description: The signature format if the source archive is signed.
          schema:
            type: string
            example: 'cms-1.0.0'
        - in: header
          name: Prefer
          description: |-
            Communicates the preference for sync vs async processing.

            Use "respond-async" to get async processing, for example "respond-async, wait=300" to wait up to 300 seconds.

            Omit this header to prefer sync processing.
          schema:
            type: string
      requestBody:
        description: A multipart payload.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                source-archive:
                  type: string
                  format: binary
                  description: The binary source archive of the package to be published
                  example: 'Binary data for Linked List package release'
                source-archive-signature:
                  type: string
                  format: binary
                  description: The signature for the source archive.
                metadata:
                  $ref: '#/components/schemas/PackageMetadata'
                metadata-signature:
                  type: string
                  format: base64
                  description: The signature for the metadata.
              required:
                - source-archive
            encoding:
              source-archive:
                contentType: application/zip
              source-archive-signature:
                contentType: application/octet-stream
              metadata:
                contentType: application/json
              metadata-signature:
                contentType: application/octet-stream
      responses:
        '201':
          description: The package release has been successfully published
          headers:
            Content-Version:
              $ref: '#/components/headers/ContentVersion'
            Location:
              description: The URL to the created release.
              schema:
                type: string
                format: uri
                example: 'https://packages.example.com/github.com/mona/LinkedList/1.1.1'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/PublishResponse'
        '202':
          description: The request to publish the package has been accepted and is being processed
          headers:
            'Retry-After':
              $ref: '#/components/headers/RetryAfter'
            Location:
              description: |-
                The URL to poll for status of the publication process.

                Poll that URL using a `GET` request, and if the response is 202, extract the Retry-After header to get a new estimate
                of when the processing will be finished.

                When the response is 301, the processing is finished and the Location header points to the new release.

                If the response is 4xx, the processing failed and you can stop polling. The response contains the failure details.

                Send `DELETE` to the URL to cancel the processing.
              schema:
                type: string
                format: uri
                description: URL to poll for status of the publication process
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          description: Method not allowed - publishing is not supported on this server.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict - an existing release already exists, or the release is still processing.
          headers:
            Location:
              description: The location of the release that's still processing, see the 202 response for details.
              schema:
                type: string
                format: uri
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '413':
          description: Content too large.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          description: Unprocessable entity - refused to publish the release.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  '/{scope}/{name}/{version}/Package.swift':
    parameters:
      - $ref: '#/components/parameters/Scope'
      - $ref: '#/components/parameters/PackageName'
      - $ref: '#/components/parameters/Version'
    get:
      tags:
        - Packages
      summary: Fetch manifest for a package release
      operationId: fetchManifestForPackageRelease
      parameters:
        - $ref: '#/components/parameters/SwiftVersion'
      responses:
        '200':
          description: Retrieve the manifest file for the specified package release
          headers:
            Link:
              required: true
              schema:
                type: string
                description: |-
                  One value for each version-specific package manifest file in the release's source archive, 
                  whose filename matches the following regular expression pattern:
                  `\APackage@swift-(\d+)(?:\.(\d+))?(?:\.(\d+))?.swift\z`

                  Each link value should have the alternate relation type, a filename attribute set to the version-specific package manifest filename 
                  (for example, Package@swift-4.swift), and a swift-tools-version attribute set to the Swift tools version specified by the package 
                  manifest file (for example, 4.0 for a manifest beginning with the comment // swift-tools-version:4.0).
          content:
            text/x-swift:
              schema:
                type: string
        '303':
          description: Redirect to the unqualified Package.swift resource.
          headers:
            Location:
              required: true
              schema:
                type: string
                format: uri
                example: 'https://packages.example.com/mona/LinkedList/1.1.1/Package.swift'
            Content-Version:
              $ref: '#/components/headers/ContentVersion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  '/{scope}/{name}/{version}.zip':
    parameters:
      - $ref: '#/components/parameters/Scope'
      - $ref: '#/components/parameters/PackageName'
      - $ref: '#/components/parameters/Version'
    get:
      tags:
        - Packages
      summary: Download source archive for a package release
      operationId: downloadSourceArchive
      responses:
        '200':
          description: Download the source archive for the specified package release
          headers:
            Digest:
              description: A digest containing a cryptographic digest of the source archive.
              schema:
                type: string
                example: 'sha-256=oqxUzyX7wa0AKPA/CqS5aDO4O7BaFOUQiSuyfepNyBI='
            Content-Disposition:
              description: |- 
                A header set to attachment with a filename parameter equal to the name of the package followed by a hyphen (-), 
                the version number, and file extension (for example, "LinkedList-1.1.1.zip")
              schema:
                type: string
                example: 'attachment; filename="LinkedList-1.1.1.zip"'
            X-Swift-Package-Signature-Format:
              description: The format of the package signature, used for integrity verification
              schema:
                type: string
                example: 'cms-1.0.0'
            X-Swift-Package-Signature:
              description: Signature of the downloaded package, used for integrity verification
              schema:
                type: string
                format: base64
                example: 'l1TdTeIuGdNsO1FQ0ptD64F5nSSOsQ5WzhM6/7KsHRuLHfTsggnyIWr0DxMcBj5F40zfplwntXAgS0ynlqvlFw=='
            Link:
              description: A header containing mirrors or multiple download locations.
              schema:
                type: string
                description: A Link header with a `duplicate` relation, as described by RFC 6249.
                example: '<https://mirror-japanwest.example.com/mona-LinkedList-1.1.1.zip>; rel=duplicate; geo=jp; pri=10; type="application/zip"'
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '303':
          description: See other - download from the URL in the Location header.
          headers:
            Location:
              description: The location from which to download the resource.
              required: true
              schema:
                type: string
                example: 'https://example.cdn.com/LinkedList-1.1.1.zip?key=XXXXXXXXXXXXXXXXX'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  '/identifiers':
    parameters:
      - $ref: '#/components/parameters/Url'
    get:
      tags:
        - Packages
      summary: Lookup package identifiers registered for a URL
      operationId: lookupPackageIdentifiersByURL
      responses:
        '200':
          description: Retrieve a list of package identifiers registered for a specific URL
          headers:
            Content-Version:
              $ref: '#/components/headers/ContentVersion'
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Identifiers'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  '/login':
    post:
      tags:
        - Authentication
      summary: Log in to the package registry
      operationId: loginToRegistry
      description: |-
        Log in using either basic or token authentication. Use the `Authorization` header to provide credentials.

        Also use this endpoint to verify authentication credentials before saving them to the local secrets store.
      responses:
        '200':
          description: User successfully logged in to the package registry
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '501':
          description: Registry does not support authentication.
components:
  parameters:
    SwiftVersion:
      name: swift-version
      in: query
      required: false
      description: The Swift version for which to fetch the manifest
      schema:
        type: string
        example: '4.2'
    Scope:
      name: scope
      in: path
      required: true
      description: |-
        The scope of the package (for example, the organization or user).
        Package scopes are case-insensitive.
      schema:
        type: string
        pattern: '[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}'
        example: 'mona'
    PackageName:
      name: name
      in: path
      required: true
      description: |-
        The name of the package.
        Package names are case-insensitive.
      schema:
        type: string
        pattern: '[a-zA-Z0-9](?:[a-zA-Z0-9]|[-_](?=[a-zA-Z0-9])){0,99}'
        example: 'LinkedList'
    Version:
      name: version
      in: path
      required: true
      description: The semantic version of the package release.
      schema:
        type: string
        example: '1.2.3'
    Url:
      name: url
      in: query
      required: true
      description: The URL for which to look up registered package identifiers
      schema:
        type: string
        example: 'https://example.com/mona/LinkedList'
  responses:
    Unauthorized:
      description: Authentication failed due to invalid credentials provided
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    BadRequest:
      description: Bad Request - The request was invalid or cannot be otherwise served
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    NotFound:
      description: Not Found - The specified resource could not be found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    UnsupportedMediaType:
      description: Unsupported Media Type - Accept header specifies a valid but unsupported API version.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      headers:
        'Retry-After':
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
  headers:
    PackageLinks:
      schema:
        type: string
        description: |- 
          A set of related links.

          An example:
          <https://github.com/mona/LinkedList>; rel="canonical",
          <ssh://git@github.com:mona/LinkedList.git>; rel="alternate",
          <https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version",
          <https://github.com/sponsors/mona>; rel="payment",
          <https://packages.example.com/mona/LinkedList?page=1>; rel="first",
          <https://packages.example.com/mona/LinkedList?page=2>; rel="previous",
          <https://packages.example.com/mona/LinkedList?page=4>; rel="next",
          <https://packages.example.com/mona/LinkedList?page=10>; rel="last"

          Another example:
          <https://packages.example.com/mona/LinkedList/1.1.1>; rel="latest-version",
          <https://packages.example.com/mona/LinkedList/1.0.0>; rel="predecessor-version"

          Also see:
          - https://www.rfc-editor.org/rfc/rfc6596.html
          - https://html.spec.whatwg.org/multipage/links.html#link-type-alternate
          - https://github.com/swiftlang/swift-package-manager/blob/main/Documentation/PackageRegistry/Registry.md#4-endpoints
    RetryAfter:
      schema:
        type: string
        description: |-
          Retry-After header, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After.

          Examples:
            Retry-After: Wed, 21 Oct 2015 07:28:00 GMT
            Retry-After: 120
        example: '120'
    ContentVersion:
      description: The content version.
      required: true
      schema:
        type: integer
        enum:
          - 1
  schemas:
    PackageOrganization:
      type: object
      properties:
        description:
          description: A description of the organization.
          type: string
        email:
          description: Email address of the organization.
          format: email
          type: string
        name:
          description: Name of the organization.
          type: string
        url:
          description: URL of the organization.
          format: uri
          type: string
      required:
        - name
    PackageAuthor:
      type: object
      properties:
        description:
          description: A description of the author.
          type: string
        email:
          description: Email address of the author.
          format: email
          type: string
        name:
          description: Name of the author.
          type: string
        organization:
          $ref: '#/components/schemas/PackageOrganization'
        url:
          description: URL of the author.
          format: uri
          type: string
      required:
        - name
    PackageMetadata:
      type: object
      description: Metadata of a package release.
      properties:
        author:
          $ref: '#/components/schemas/PackageAuthor'
        description:
          type: string
          description: A description of the package release.
        licenseURL:
          type: string
          format: uri
          description: URL of the package release's license document.
        originalPublicationTime:
          type: string
          format: date-time
          description: Original publication time of the package release in ISO 8601 format.
        readmeURL:
          type: string
          format: uri
          description: URL of the README specifically for the package release or broadly
            for the package.
        repositoryURLs:
          type: array
          items:
            description: Code repository URL.
            type: string
            format: uri
          description: Code repository URL(s) of the package release.
    PublishResponse:
      type: object
      properties:
        message:
          type: string
          example: 'Package release successfully published'
        url:
          type: string
          format: uri
          description: The URL of the newly published package release
          example: 'https://packages.example.com/mona/LinkedList/1.1.0'
    ProblemDetails:
      type: object
      description: A problem detail object conforming to RFC7807
      properties:
        type:
          type: string
          format: uri
          description: |-
            A URI reference that identifies the problem type.
            This specification encourages that, when dereferenced, 
            it provides human-readable documentation for the problem type.
          example: 'https://example.com/problem/invalid-request-parameters'
        title:
          type: string
          description: |-
            A short, human-readable summary of the problem type. 
            It should not change from occurrence to occurrence of the
            problem, except for purposes of localization.
          example: 'Invalid request parameters'
        status:
          type: integer
          description: |-
            The HTTP status code generated by the origin server for this occurrence of the problem.
          example: 400
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          example: 'The "name" field is required.'
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem.
          example: '/requests/12345'
      additionalProperties: true
    ListedRelease:
      type: object
      properties:
        url:
          type: string
          format: uri
          example: 'https://packages.example.com/mona/LinkedList/1.1.0'
        problem:
          $ref: '#/components/schemas/ProblemDetails'
    Releases:
      type: object
      properties:
        releases:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ListedRelease'
      required:
        - releases
    ReleaseSignature:
      type: object
      properties:
        signatureBase64Encoded:
          type: string
          format: base64
          description: The resource's signature, base64 encoded.
          example: 'dGVzdFNpZ25hdHVyZQ=='
        signatureFormat:
          type: string
          description: The signature format.
          example: 'cms-1.0.0'
      required:
        - signatureBase64Encoded
        - signatureFormat
    ReleaseResource:
      type: object
      properties:
        name:
          type: string
          description: The name of the resource.
          example: 'source-archive'
        type:
          type: string
          description: The content type of the resource.
          example: 'application/zip'
        checksum:
          type: string
          description: A hexadecimal representation of the SHA256 digest for the resource.
          example: 'efaa6545cd99dd1e124b5269ea0586994b6d97a0443021d2966e1df6dec9c4a1'
        signing:
          $ref: '#/components/schemas/ReleaseSignature'
      required:
        - name
        - type
        - checksum
    ReleaseMetadata:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Identifier'
        version:
          type: string
          description: The package release version number.
          example: '1.2.3'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/ReleaseResource'
          description: The resources available for the release.
        metadata:
          $ref: '#/components/schemas/PackageMetadata'
        publishedAt:
          type: string
          format: date-time
          description: |-
            The ISO 8601-formatted datetime string of when the package release was published, as recorded by the registry. 
            See related `originalPublicationTime` in metadata.
      required:
        - id
        - version
        - resources
        - metadata
    Identifier:
      type: string
      example: 'mona.LinkedList'
    Identifiers:
      type: object
      properties:
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/Identifier'
      required:
        - identifiers