Apicurio Branches API

openapi: 3.1.0
info:
  title: Apicurio Registry Admin Branches API
  version: 3.1.x
  description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
  contact:
    name: Apicurio
    url: https://www.apicur.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
  description: Local Apicurio Registry
tags:
- name: Branches
paths:
  /groups/{groupId}/artifacts/{artifactId}/branches:
    summary: Manage branches of an artifact.
    parameters:
    - name: groupId
      description: The artifact group ID.  Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/GroupId'
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.  Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/ArtifactId'
      in: path
      required: true
    get:
      tags:
      - Branches
      parameters:
      - name: offset
        description: The number of branches to skip before starting to collect the result set.  Defaults to 0.
        schema:
          type: integer
        in: query
        required: false
      - name: limit
        description: The number of branches to return.  Defaults to 20.
        schema:
          type: integer
        in: query
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchSearchResults'
          description: List of all artifact versions.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: listBranches
      summary: List branches
      description: 'Returns a list of all branches in the artifact. Each branch is a list of version identifiers,

        ordered from the latest (tip of the branch) to the oldest.


        This operation can fail for the following reasons:


        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)

        '
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBranch'
        required: true
      tags:
      - Branches
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchMetaData'
          description: Branch successfully created.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: createBranch
      summary: Create a new branch
      description: 'Creates a new branch for the artifact.  A new branch consists of metadata and a

        list of versions.


        This operation can fail for the following reasons:


        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * A branch with the given `branchId` already exists (HTTP error `409`)

        * A server error occurred (HTTP error `500`)

        '
  /groups/{groupId}/artifacts/{artifactId}/branches/{branchId}:
    summary: Manage a single branch.
    parameters:
    - name: groupId
      description: The artifact group ID.  Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/GroupId'
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.  Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/ArtifactId'
      in: path
      required: true
    - name: branchId
      description: Artifact branch ID.  Must follow the "[a-zA-Z0-9._\\-+]{1,256}" pattern.
      schema:
        $ref: '#/components/schemas/BranchId'
      in: path
      required: true
    get:
      tags:
      - Branches
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchMetaData'
          description: List of versions in an artifact branch.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: getBranchMetaData
      summary: Get branch metaData
      description: 'Returns the metaData of a branch.


        This operation can fail for the following reasons:


        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * No branch with this `branchId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)

        '
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditableBranchMetaData'
        required: true
      tags:
      - Branches
      responses:
        '204':
          description: List of versions in an artifact branch.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: updateBranchMetaData
      summary: Update branch metaData
      description: 'Updates the metadata of a branch.


        This operation can fail for the following reasons:

        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * No branch with this `branchId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)

        '
    delete:
      tags:
      - Branches
      responses:
        '204':
          description: Artifact branch was successfully deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: deleteBranch
      summary: Delete branch.
      description: 'Deletes a single branch in the artifact.


        This operation can fail for the following reasons:

        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * No branch with this `branchId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)

        '
  /groups/{groupId}/artifacts/{artifactId}/branches/{branchId}/versions:
    summary: Manage the versions in a branch.
    parameters:
    - name: groupId
      description: The artifact group ID.  Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/GroupId'
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.  Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/ArtifactId'
      in: path
      required: true
    - name: branchId
      description: Artifact branch ID.  Must follow the "[a-zA-Z0-9._\\-+]{1,256}" pattern.
      schema:
        $ref: '#/components/schemas/BranchId'
      in: path
      required: true
    get:
      tags:
      - Branches
      parameters:
      - name: offset
        description: The number of versions to skip before starting to collect the result set.  Defaults to 0.
        schema:
          type: integer
        in: query
        required: false
      - name: limit
        description: The number of versions to return.  Defaults to 20.
        schema:
          type: integer
        in: query
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionSearchResults'
          description: The list of versions in the branch.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: listBranchVersions
      summary: Get versions in branch
      description: "Get a list of all versions in the branch.  Returns a list of version identifiers in the branch, \nordered from the latest (tip of the branch) to the oldest.\n\nThis operation can fail for the following reasons:\n* No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)\n* No branch with this `branchId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)\n"
    put:
      requestBody:
        description: A new list of versions that should be on the branch.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceBranchVersions'
        required: true
      tags:
      - Branches
      responses:
        '204':
          description: The list of versions was replaced successfully.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: replaceBranchVersions
      summary: Replace list of versions in branch
      description: 'Add a new version to an artifact branch. Branch is created if it does not exist. Returns a list of version identifiers in the artifact branch, ordered from the latest (tip of the branch) to the oldest.

        This operation can fail for the following reasons:

        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * No branch with this `branchId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)

        '
    post:
      requestBody:
        description: The version to add to the branch.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddVersionToBranch'
        required: true
      tags:
      - Branches
      responses:
        '204':
          description: The version was successfully added to the branch.
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: addVersionToBranch
      summary: Add a new version to a branch.
      description: 'Add a new version to an artifact branch. Returns a list of version identifiers in the branch, ordered from the latest (tip of the branch) to the oldest.


        This operation can fail for the following reasons:

        * No artifact with this `groupId` and `artifactId` exists (HTTP error `404`)

        * No branch with this `branchId` exists (HTTP error `404`)

        * Branch already contains the given version. Artifact branches are append-only, cycles and history rewrites, except by replacing the entire branch using the replaceBranchVersions operation,  are not supported. (HTTP error `409`)

        * A server error occurred (HTTP error `500`)

        '
components:
  responses:
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ForbiddenExample:
              value:
                detail: 'ForbiddenException: User is not authorized to perform this operation.'
                title: User is not authorized to perform this operation.
                status: 403
                name: ForbiddenException
      description: Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            UnauthorizedExample:
              value:
                detail: 'UnauthorizedException: User is not authenticated.'
                title: User is not authenticated.
                status: 401
                name: UnauthorizedException
      description: Common response for all operations that can return a `401` error indicating authentication is required.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            NotFoundExample:
              value:
                error_code: 404
                message: No artifact with id 'Topic-1/Inbound' could be found.
      description: Common response for all operations that can return a `404` error.
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ConflictExample:
              value:
                error_code: 409
                message: The artifact content was invalid.
      description: Common response used when an input conflicts with existing data.
    ServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ErrorExample:
              value:
                error_code: 500
                message: Lost connection to the database.
      description: Common response for all operations that can fail with an unexpected server error.
  schemas:
    Version:
      description: 'A single version of an artifact.  Can be provided by the client when creating a new version,

        or it can be server-generated.  The value can be any string unique to the artifact, but it is

        recommended to use a simple integer or a semver value.'
      pattern: ^[a-zA-Z0-9._\-+]{1,256}$
      type: string
      example: '"3.1.6"'
    SearchedBranch:
      title: Root Type for SearchedBranch
      description: ''
      required:
      - groupId
      - artifactId
      - branchId
      - createdOn
      - owner
      - modifiedBy
      - modifiedOn
      - systemDefined
      type: object
      properties:
        groupId:
          $ref: '#/components/schemas/GroupId'
          description: ''
        artifactId:
          $ref: '#/components/schemas/ArtifactId'
          description: ''
        branchId:
          $ref: '#/components/schemas/BranchId'
          description: ''
        createdOn:
          format: date-time
          description: ''
          type: string
        owner:
          description: ''
          type: string
        modifiedOn:
          format: date-time
          description: ''
          type: string
        modifiedBy:
          description: ''
          type: string
        description:
          description: ''
          type: string
        systemDefined:
          description: ''
          type: boolean
      example:
        groupId: ExampleGroup
        artifactId: ExampleArtifact
        branchId: 1.0.x
        description: A really nice branch.
        systemDefined: false
        createdOn: 2018-02-10T09:30Z
        owner: user1
        modifiedOn: 2019-03-11T09:30Z
        modifiedBy: user2
    Labels:
      description: User-defined name-value pairs. Name and value must be strings.
      type: object
      additionalProperties:
        type: string
      x-codegen-inline: true
      x-codegen-type: StringMap
    GroupId:
      description: An ID of a single artifact group.
      pattern: ^.{1,512}$
      type: string
      example: '"my-group"'
    VersionSearchResults:
      description: Describes the response received when searching for artifacts.
      required:
      - count
      - versions
      type: object
      properties:
        count:
          description: 'The total number of versions that matched the query (may be more than the number of versions

            returned in the result set).'
          type: integer
        versions:
          description: The collection of artifact versions returned in the result set.
          type: array
          items:
            $ref: '#/components/schemas/SearchedVersion'
    ArtifactType:
      description: ''
      type: string
      example: AVRO
      x-codegen-package: io.apicurio.registry.types
    VersionState:
      description: 'Describes the state of an artifact or artifact version.


        * ENABLED

        * DISABLED

        * DEPRECATED

        * DRAFT

        * SUNSET — Signals that a migration deadline has passed and the version will be removed. Requires transitioning through DEPRECATED first. Added in 3.3.0.

        '
      enum:
      - ENABLED
      - DISABLED
      - DEPRECATED
      - DRAFT
      - SUNSET
      type: string
      x-codegen-package: io.apicurio.registry.types
    ArtifactId:
      description: The ID of a single artifact.
      pattern: ^.{1,512}$
      type: string
      example: '"example-artifact"'
    BranchId:
      description: The ID of a single artifact branch.
      pattern: ^[a-zA-Z0-9._\-+]{1,256}$
      type: string
      example: '"latest"'
    CreateBranch:
      title: Root Type for CreateBranch
      description: ''
      required:
      - branchId
      type: object
      properties:
        description:
          type: string
        branchId:
          $ref: '#/components/schemas/BranchId'
          description: ''
        versions:
          description: ''
          type: array
          items:
            $ref: '#/components/schemas/Version'
      example:
        branchId: 1.0.x
        description: The description of the branch.
    ProblemDetails:
      title: Root Type for Error
      description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response

        body.'
      required:
      - title
      - status
      type: object
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        type:
          description: A URI reference [RFC3986] that identifies the problem type.
          type: string
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        status:
          format: int32
          description: The HTTP status code.
          type: integer
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          type: string
        name:
          description: The name of the error (typically a server exception class name).
          type: string
      example:
        status: 500
        name: NullPointerException
        title: An error occurred somewhere.
    ReplaceBranchVersions:
      description: ''
      required:
      - versions
      type: object
      properties:
        versions:
          description: ''
          type: array
          items:
            $ref: '#/components/schemas/Version'
    EditableBranchMetaData:
      title: Root Type for EditableArtifactMetaData
      description: ''
      type: object
      properties:
        description:
          type: string
      example:
        description: The description of the group.
    BranchSearchResults:
      description: Describes the response received when searching for branches.
      required:
      - count
      - branches
      type: object
      properties:
        branches:
          description: The branches returned in the result set.
          type: array
          items:
            $ref: '#/components/schemas/SearchedBranch'
        count:
          description: "The total number of branches that matched the query that produced the result set (may be \nmore than the number of branches in the result set)."
          type: integer
    BranchMetaData:
      title: Root Type for BranchMetaData
      description: ''
      required:
      - groupId
      - artifactId
      - branchId
      - createdOn
      - modifiedOn
      - modifiedBy
      - owner
      - systemDefined
      type: object
      properties:
        groupId:
          $ref: '#/components/schemas/GroupId'
          description: ''
        artifactId:
          $ref: '#/components/schemas/ArtifactId'
          description: ''
        branchId:
          $ref: '#/components/schemas/BranchId'
          description: ''
        createdOn:
          format: date-time
          type: string
        modifiedBy:
          type: string
        modifiedOn:
          format: date-time
          type: string
        owner:
          description: ''
          type: string
        description:
          description: ''
          type: string
        systemDefined:
          description: ''
          type: boolean
      example:
        groupId: ExampleGroup
        artifactId: ExampleArtifact
        branchId: 1.0.x
        description: Just an example branch.
        systemDefined: false
        createdOn: 2018-02-10T09:30Z
        modifiedBy: user1
        modifiedOn: 2020-02-10T09:30Z
        owner: user2
    AddVersionToBranch:
      description: ''
      required:
      - version
      type: object
      properties:
        version:
          description: ''
          type: string
    SearchedVersion:
      description: Models a single artifact from the result set returned when searching for artifacts.
      required:
      - owner
      - createdOn
      - artifactType
      - state
      - globalId
      - version
      - contentId
      - artifactId
      type: object
      properties:
        name:
          description: ''
          type: string
        description:
          description: ''
          type: string
        createdOn:
          format: date-time
          description: ''
          type: string
        owner:
          description: ''
          type: string
        artifactType:
          $ref: '#/components/schemas/ArtifactType'
          description: ''
        state:
          $ref: '#/components/schemas/VersionState'
          description: ''
        globalId:
          format: int64
          description: ''
          type: integer
        version:
          $ref: '#/components/schemas/Version'
          description: ''
        contentId:
          format: int64
          description: ''
          type: integer
        artifactId:
          $ref: '#/components/schemas/ArtifactId'
          description: ''
        groupId:
          $ref: '#/components/schemas/GroupId'
          description: ''
        modifiedBy:
          description: ''
          type: string
        modifiedOn:
          format: date-time
          description: ''
          type: string
        labels:
          $ref: '#/components/schemas/Labels'
          description: ''
      example:
        groupId: DemoGroup
        artifactId: demo-artifact-id
        name: Artifact Version Name
        description: Description of the artifact version
        artifactType: AVRO
        state: ENABLED
        createdOn: 2018-02-10T09:30Z
        owner: some text
        globalId: 37
        version: 1.0.7
        contentId: 62
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token
          scopes:
            read: Read access
            write: Write access
            admin: Admin access
x-codegen:
  suppress-date-time-formatting: true
  bean-annotations:
  - io.quarkus.runtime.annotations.RegisterForReflection
  - annotation: lombok.experimental.SuperBuilder
    excludeEnums: true
  - annotation: lombok.AllArgsConstructor
    excludeEnums: true
  - annotation: lombok.NoArgsConstructor
    excludeEnums: true
  - annotation: lombok.EqualsAndHashCode
    excludeEnums: true
  - annotation: lombok.ToString(callSuper = true)
    excludeEnums: true