openapi: 3.1.0
info:
  title: Apicurio Registry Admin Artifact rules 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: Artifact rules
paths:
  /groups/{groupId}/artifacts/{artifactId}/rules:
    summary: Manage the rules for a single 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:
      - Artifact rules
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuleType'
          description: Returns the names of the rules configured for the artifact.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: listArtifactRules
      summary: List artifact rules
      description: "Returns a list of all rules configured for the artifact.  The set of rules determines\nhow the content of an artifact can evolve over time.  If no rules are configured for\nan artifact, then the rules configured for the group is used.  If no rules are \nconfigured at the group level, then the set of globally configured rules are used.  \nIf no global rules are defined, there are no restrictions on content evolution.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* A server error occurred (HTTP error `500`)"
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRule'
        required: true
      tags:
      - Artifact rules
      responses:
        '204':
          description: The rule was added.
        '400':
          $ref: '#/components/responses/BadRequest'
        '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: createArtifactRule
      summary: Create artifact rule
      description: 'Adds a rule to the list of rules that get applied to the artifact when adding new

        versions.  All configured rules must pass to successfully add a new artifact version.


        This operation can fail for the following reasons:


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

        * Rule (named in the request body) is unknown (HTTP error `400`)

        * Rule is already configured (HTTP error `409`)

        * A server error occurred (HTTP error `500`)'
    delete:
      tags:
      - Artifact rules
      responses:
        '204':
          description: The rules were successfully deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: deleteArtifactRules
      summary: Delete artifact rules
      description: 'Deletes all of the rules configured for the artifact.  After this is done, the global

        rules apply to the artifact again.


        This operation can fail for the following reasons:


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

        * A server error occurred (HTTP error `500`)'
  /groups/{groupId}/artifacts/{artifactId}/rules/{ruleType}:
    summary: Manage the configuration of a single artifact rule.
    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: ruleType
      description: The unique name/type of a rule.
      schema:
        enum:
        - VALIDITY
        - COMPATIBILITY
        - INTEGRITY
        type: string
      in: path
      required: true
    get:
      tags:
      - Artifact rules
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
          description: Information about a rule.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: getArtifactRuleConfig
      summary: Get artifact rule configuration
      description: 'Returns information about a single rule configured for an artifact.  This is useful

        when you want to know what the current configuration settings are for a specific rule.


        This operation can fail for the following reasons:


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

        * No rule with this name/type is configured for this artifact (HTTP error `404`)

        * Invalid rule type (HTTP error `400`)

        * A server error occurred (HTTP error `500`)'
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Rule'
        required: true
      tags:
      - Artifact rules
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Rule'
          description: Rule configuration was updated.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: updateArtifactRuleConfig
      summary: Update artifact rule configuration
      description: "Updates the configuration of a single rule for the artifact.  The configuration data\nis specific to each rule type, so the configuration of the `COMPATIBILITY` rule \nis in a different format from the configuration of the `VALIDITY` rule.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)\n"
    delete:
      tags:
      - Artifact rules
      responses:
        '204':
          description: The rule was successfully deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: deleteArtifactRule
      summary: Delete artifact rule
      description: "Deletes a rule from the artifact.  This results in the rule no longer applying for\nthis artifact.  If this is the only rule configured for the artifact, this is the \nsame as deleting **all** rules, and the globally configured rules now apply to\nthis artifact.\n\nThis operation can fail for the following reasons:\n\n* No artifact with this `artifactId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this artifact (HTTP error `404`)\n* Invalid rule type (HTTP error `400`)\n* A server error occurred (HTTP error `500`)"
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Common response for all operations that can return a `400` error.
    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.
    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.
    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.
    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.
    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:
    GroupId:
      description: An ID of a single artifact group.
      pattern: ^.{1,512}$
      type: string
      example: '"my-group"'
    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.
    Rule:
      title: Root Type for Rule
      description: ''
      required:
      - config
      type: object
      properties:
        config:
          type: string
        ruleType:
          $ref: '#/components/schemas/RuleType'
      example:
        ruleType: VALIDITY
        config: FULL
    RuleType:
      description: ''
      enum:
      - VALIDITY
      - COMPATIBILITY
      - INTEGRITY
      type: string
      example: VALIDITY
      x-codegen-package: io.apicurio.registry.types
    CreateRule:
      title: Root Type for Rule
      description: ''
      required:
      - config
      type: object
      properties:
        config:
          type: string
        ruleType:
          $ref: '#/components/schemas/RuleType'
      example:
        ruleType: VALIDITY
        config: FULL
    ArtifactId:
      description: The ID of a single artifact.
      pattern: ^.{1,512}$
      type: string
      example: '"example-artifact"'
  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