openapi.yaml

openapi: 3.0.0
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/SpongePowered/Downloads/1.0.0
  - description: SpongePowered Production Downloads API
    url: https://dl-api.spongepowered.org/v2
info:
  version: "1.0.0"
  title: downloads-api
  description: The API for Downloads Indexing
paths:
  /groups:
    get:
      tags:
        - Groups
      description: returns all registered groups with the service
      operationId: getGroups
      responses:
        '200':
          description: All groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Groups'
    post:
      tags:
        - Groups
      description: registers a new group
      operationId: registerGroup
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '201':
          description: Group registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
  '/groups/{groupID}':
    get:
      tags:
        - Groups
      operationId: getGroup
      parameters:
        - $ref: '#/components/parameters/GroupID'
      responses:
        '200':
          description: response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '404':
          description: Group not found
  /groups/{groupID}/artifacts:
    get:
      tags:
        - Artifacts
      operationId: getArtifacts
      parameters:
        - $ref: '#/components/parameters/GroupID'
      responses:
        '200':
          description: Artifacts indexed for the group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupArtifacts'
    post:
      tags:
        - Artifacts
      description: registers a new artifact under a group
      operationId: registerArtifact
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/GroupID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactRegistration'
      responses:
        '201':
          description: Artifact registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
        '400':
          description: Bad request - invalid or missing request body
        '404':
          description: Group not found
        '409':
          description: Artifact already exists in the group
  '/groups/{groupID}/artifacts/{artifactID}':
    get:
      tags:
        - Artifacts
      operationId: getArtifact
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
      responses:
        '200':
          description: Artifact details indexed and maintained, such as repository, version tags, issues, website, etc.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
        '404':
          description: Artifact not found
    patch:
      tags:
        - Artifacts
      operationId: updateArtifact
      security:
        - bearerAuth: []
      description: Updates mutable fields on an artifact. Only fields present in the request body are changed.
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                  description: Display name for the artifact
                gitRepository:
                  type: array
                  items:
                    type: string
                    format: URL
                  description: Git repository URLs
                website:
                  type: string
                  format: URL
                issues:
                  type: string
                  format: URL
      responses:
        '200':
          description: Artifact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
        '404':
          description: Artifact not found
  '/groups/{groupID}/artifacts/{artifactID}/sync':
    post:
      tags:
        - Artifacts
      operationId: triggerSync
      security:
        - bearerAuth: []
      description: |
        Triggers an immediate version sync for the artifact by firing its
        Temporal Schedule. Use this from CI (e.g. GitHub Actions) after
        publishing a new version to Sonatype so SOAD indexes it without
        waiting for the next polling interval.
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
        - in: query
          name: source
          schema:
            type: string
            enum: [metadata, search]
          required: false
          description: |
            Which version-discovery schedule to trigger. `metadata` fires the
            fast 2-minute maven-metadata.xml schedule; `search` fires the
            hourly REST-pagination correctness backstop schedule. Defaults
            to `metadata` (the fast path) when omitted.
      responses:
        '200':
          description: Sync triggered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "sync triggered"
        '400':
          description: Invalid source value
        '404':
          description: No sync schedule found for this artifact (artifact may not be registered)
        '500':
          description: Internal error triggering sync
  '/groups/{groupID}/artifacts/{artifactID}/schema':
    get:
      tags:
        - Artifacts
      operationId: getArtifactSchema
      description: Returns the version schema for an artifact
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
      responses:
        '200':
          description: The version schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionSchema'
        '404':
          description: Artifact not found or no schema set
    put:
      tags:
        - Artifacts
      operationId: putArtifactSchema
      security:
        - bearerAuth: []
      description: Replaces the version schema for an artifact. Triggers recomputation of version ordering and tags.
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionSchema'
      responses:
        '200':
          description: Schema updated, ordering recomputation triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionSchema'
        '400':
          description: Invalid schema (bad regex, missing segments, unknown parse_as)
        '404':
          description: Artifact not found
  '/groups/{groupID}/artifacts/{artifactID}/latest':
    get:
      tags:
        - Versions
      operationId: getLatestVersion
      description: Returns the latest version for an artifact, optionally filtered by tags.
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
        - name: recommended
          required: false
          in: query
          schema:
            type: boolean
            description: If true, only consider versions marked as recommended.
        - name: tags
          required: false
          in: query
          schema:
            type: string
            description: |
              Tag filter to find the latest version matching specific tags.
              Same format as getVersions: colon-separated key:value pairs,
              comma-separated for multiple. Supports prefix matching.
            example: "minecraft:1.21.11"
      responses:
        '200':
          description: The latest version matching the filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfo'
        '404':
          description: Artifact not found or no versions match the filter
  '/groups/{groupID}/artifacts/{artifactID}/versions':
    get:
      tags:
        - Artifacts
        - Versions
      operationId: getVersions
      parameters:
        - $ref: '#/components/parameters/GroupID'
        - $ref: '#/components/parameters/ArtifactID'
        - name: recommended
          required: false
          in: query
          schema:
            type: boolean
        - name: limit
          required: false
          in: query
          schema:
            type: integer
            maximum: 25
            minimum: 1
        - name: offset
          required: false
          in: query
          schema:
            type: integer
            minimum: 0
        - name: tags
          required: false
          in: query
          schema:
            type: string
            description: |
              A colon tag value pair separated by commas to filter 
              versions of a desired set of tags. An example can be
              'minecraft:1.12,api:7.4'
          example: "minecraft:1.12.2,api:7.4"
      responses:
        '200':
          description: The versions available
          content:
            application/json:
              schema:
                type: object
                properties:
                  artifacts:
                    type: object
                    example:
                      "1.16.5-36.2.5-8.1.0-RC1331":
                        tagValues:
                          minecraft: "1.16.5"
                          forge: "36.2.5"
                          api: "8.1"
                        recommended: false
                    additionalProperties:
                      type: object
                      properties:
                        tagValues:
                          type: object
                          additionalProperties:
                            type: string
                        recommended:
                          type: boolean
                  offset:
                    type: integer
                    description: The offset used for this page of results
                    example: 0
                  limit:
                    type: integer
                    description: The limit used for this page of results
                    example: 25
                  size:
                    type: integer
                    description: Total number of versions matching the query (for pagination)
                    example: 142
        '404':
          description: Artifact not found
  '/groups/{groupID}/artifacts/{artifactID}/versions/{versionID}':
    get:
      tags:
        - Versions
      operationId: getVersionInfo
      parameters:
        - name: groupID
          in: path
          example: org.spongepowered
          schema:
            type: string
          description: The maven style group coordinates
          required: true
        - name: artifactID
          in: path
          schema:
            type: string
          example: spongeforge
          description: The maven style artifact id
          required: true
        - name: versionID
          in: path
          required: true
          example: "1.16.5-36.2.5-8.1.0-RC1331"
          schema:
            type: string
      responses:
        '200':
          description: The version details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionInfo'
        '404':
          description: Version not found
components:
  schemas:
    Group:
      required:
        - groupCoordinates
        - name
      type: object
      properties:
        groupCoordinates:
          type: string
          description: Maven style group coordinates
        name:
          type: string
          description: The name of the group
        website:
          type: string
          description: The website url
    Groups:
      type: object
      required:
        - groups
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/Group'
    GroupDetails:
      type: object
      required:
        - type
        - group
      properties:
        type:
          type: string
          example: Group
        group:
          type: object
          example:
            groupCoordinates: "org.spongepowered"
            name: "SpongePowered"
            website: "https://spongepowered.org/"
          properties:
            groupCoordinates:
              type: string
              description: The maven style group coordinates
            name:
              type: string
              description: The name of the group
            website:
              type: string
              description: the website URL of the group
    GroupArtifacts:
      type: object
      required:
        - type
        - artifactIds
      properties:
        type:
          type: string
          example: Artifacts
        artifactIds:
          type: array
          items:
            type: string
          example:
            - spongevanilla
            - spongeforge
          description: The artifact id's indexed for the group
    Commit:
      type: object
      properties:
        message:
          type: string
          example: "Add missing call to BlockEntityArchetypeVolume"
        body:
          type: string
          example: |
            Add missing call to BlockEntityArchetypeVolume

        sha:
          type: string
          example: "10dfa6bb1248839347c845b5d7e3444885bbad49"
        author:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
        link:
          type: string
          format: URL
          example: "https://github.com/SpongePowered/Sponge/commit/10dfa6bb1248839347c845b5d7e3444885bbad49"
        commitDate:
          type: string
          format: date
          example: "2023-05-20T16:37:42Z"
    Asset:
      type: object
      properties:
        classifier:
          type: string
          example: ""
          description: |
            The classifier of the jar asset. Usually can be
            understood as the "variant" of the asset. Some
            variants are specific to an operating sytem, while
            others are variants of the executable available. In
            the case of Sponge's main assets, the empty string
            classifier is the "download and run" asset desired.
        downloadUrl:
          type: string
          format: URL
          example: "https://repo.spongepowered.org/repository/maven-releases/org/spongepowered/spongeforge/1.16.5-36.2.5-8.1.0-RC1331/spongeforge-1.16.5-36.2.5-8.1.0-RC1331.jar"
          description: The direct download URL
        md5:
          type: string
          example: "74a08ef0f838bd7a4a60af59a9812cb2"
        sha1:
          type: string
          example: "fb521aabc333533ea329ed2fd826025310766133"
        extension:
          type: string
          example: "jar"
          description: The file extension of the asset.
    Artifact:
      type: object
      required:
        - type
        - coordinates
        - tags
      properties:
        type:
          type: string
          example: latest
        coordinates:
          type: object
          required:
            - groupId
            - artifactId
          properties:
            groupId:
              type: string
              example: org.spongepowered
            artifactId:
              type: string
              example: spongeforge
        displayName:
          type: string
          example: SpongeForge
          description: The name of the artifact in the desired format to be displayed on the web or referenced in communication
        website:
          type: string
        gitRepository:
          type: array
          items:
            type: string
            format: URL
        issues:
          type: string
          format: URL
        tags:
          type: object
          example:
            api:
              - "8.1"
              - "8.0"
              - "7.4"
              - "7.3"
              - "7.2"
              - "7.1"
            minecraft:
              - "1.16.5"
              - "1.12.2"
          additionalProperties:
            type: array
            items:
              type: string
    ArtifactRegistration:
      type: object
      required:
        - artifactId
        - displayName
        - gitRepository
      properties:
        artifactId:
          type: string
          example: spongeforge
          description: The maven style artifact id
        displayName:
          type: string
          example: SpongeForge
          description: The name of the artifact in the desired format to be displayed on the web or referenced in communication
        gitRepository:
          type: array
          items:
            type: string
            format: URL
          example: 
            - "https://github.com/SpongePowered/Sponge"
          description: An array of git repository URLs
        website:
          type: string
          format: URL
          example: "https://spongepowered.org/"
          description: The website URL (optional)
        issues:
          type: string
          format: URL
          example: "https://github.com/SpongePowered/Sponge/issues"
          description: The issues/tracker URL (optional)
    VersionInfo:
      type: object
      properties:
        coordinates:
          type: object
          properties:
            groupId:
              type: string
              example: "org.spongepowered"
            artifactId:
              type: string
              example: "spongeforge"
            version:
              type: string
              example: "1.16.5-36.2.5-8.1.0-RC1331"
        commit:
          type: object
          properties:
            commits:
              type: array
              items:
                type: object
                properties:
                  commit:
                    $ref: '#/components/schemas/Commit'
                  submoduleCommits:
                    type: array
                    items:
                      $ref: '#/components/schemas/Commit'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'
        tags:
          type: object
          additionalProperties:
            type: string
          example:
            minecraft: "1.16.5"
            forge: "36.2.5"
            api: "8.1"
        recommended:
          type: boolean
          description: Whether the artifact is considered a "standard release" version or if it is still in development.
          example: false
    VersionSchema:
      type: object
      required:
        - variants
      properties:
        use_mojang_manifest:
          type: boolean
          description: Whether to fetch Mojang version manifest for Minecraft version ordering
          default: false
        variants:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - name
              - pattern
              - segments
            properties:
              name:
                type: string
                description: Human-readable variant name (e.g. "current", "beta-era")
                example: "current"
              pattern:
                type: string
                description: Regex with named capture groups for version parsing
                example: "^(?P<minecraft>\\d+\\.\\d+(?:\\.\\d+)?)-(?P<api>\\d+\\.\\d+\\.\\d+)$"
              segments:
                type: array
                items:
                  type: object
                  required:
                    - name
                    - parse_as
                  properties:
                    name:
                      type: string
                      description: Named capture group to match
                    parse_as:
                      type: string
                      enum: [minecraft, dotted, integer, ignore]
                      description: How to parse and compare this segment
                    tag_key:
                      type: string
                      description: If set, produces a version tag with this key
  parameters:
    GroupID:
      name: groupID
      in: path
      schema:
        type: string
      description: The maven style group coordinates
      required: true
    ArtifactID:
      name: artifactID
      in: path
      schema:
        type: string
      description: The maven style artifact id
      required: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Admin API token passed via ADMIN_API_TOKEN env var