Apicurio Group rules API

openapi: 3.1.0
info:
  title: Apicurio Registry Admin Group 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: Group rules
paths:
  /groups/{groupId}/rules:
    summary: Manage the rules for a group.
    parameters:
    - name: groupId
      description: The 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
    get:
      tags:
      - Group rules
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuleType'
          description: Returns the names of the rules configured for the group.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: listGroupRules
      summary: List group rules
      description: "Returns a list of all rules configured for the group.  The set of rules determines\nhow the content of an artifact in the group can evolve over time.  If no rules are \nconfigured for a group, the set of globally configured rules are used.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` 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:
      - Group 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: createGroupRule
      summary: Create group rule
      description: 'Adds a rule to the list of rules that get applied to an artifact in the group 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 group with this `groupId` 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:
      - Group 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: deleteGroupRules
      summary: Delete group rules
      description: 'Deletes all of the rules configured for the group.  After this is done, the global

        rules apply to artifacts in the group again.


        This operation can fail for the following reasons:


        * No group with this `groupId` exists (HTTP error `404`)

        * A server error occurred (HTTP error `500`)'
  /groups/{groupId}/rules/{ruleType}:
    summary: Manage the configuration of a single group rule.
    parameters:
    - name: groupId
      description: The 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: ruleType
      description: The unique name/type of a rule.
      schema:
        enum:
        - VALIDITY
        - COMPATIBILITY
        - INTEGRITY
        type: string
      in: path
      required: true
    get:
      tags:
      - Group 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: getGroupRuleConfig
      summary: Get group rule configuration
      description: 'Returns information about a single rule configured for a group.  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 group with this `groupId` 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:
      - Group 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: updateGroupRuleConfig
      summary: Update group rule configuration
      description: "Updates the configuration of a single rule for the group.  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 group with this `groupId` 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:
      - Group 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: deleteGroupRule
      summary: Delete group rule
      description: "Deletes a rule from the group.  This results in the rule no longer applying for\nthis group.  If this is the only rule configured for the group, this is the \nsame as deleting **all** rules, and the globally configured rules now apply to\nthis group.\n\nThis operation can fail for the following reasons:\n\n* No group with this `groupId` exists (HTTP error `404`)\n* No rule with this name/type is configured for this group (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
  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