swagger.yaml

openapi: 3.0.0
info:
  title: Azure Schema Registry Rest Service
  version: 1.0.0-beta
paths:
  /$schemagroups:
    get:
      summary: 'Get list of schema groups'
      description: 'Get all schema groups in namespace.'
      operationId: getGroups
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: string
      tags:
      -  'groups'
  /$schemas/ids/{schema-guid}:
    get:
      summary: Get schema by GUID
      description: Get schema by GUID.
      operationId: getSchemaById
      parameters:
      - name: schema-guid
        in: path
        description: schema guid referencing specific schema in registry namespace
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          $ref: '#/components/responses/SchemaBytePayloadResponse'
        '404':
          description: Schema with matching GUID not found
      tags:
        - 'runtime'
  /$schemagroups/{group-name}:
    parameters:
      - name: group-name
        in: path
        description: schema group
        required: true
        schema:
          type: string
    get:
      summary: Get schema group
      description: Get schema group description in registry namespace.
      operationId: getGroup
      responses:
        '200': 
          description: OK
          headers:
            X-Serialization:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemaGroup'
        '404':
          description: Specified group not found
      tags:
      - 'groups'
    put:
      summary: Create schema group
      description: Create schema group with specified serialization format in registry namespace.
      operationId: createGroup 
      requestBody:
        description: schema group description
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaGroup'
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema:
                type: string
        '409':
          description: Schema group already exists
      tags:
      -  'groups'
    delete:
      summary: Delete schema group
      description: Delete schema group in schema registry namespace.
      operationId: deleteGroup
      responses:
        '204':
          description: OK no content
        '404':
          description: Specified group not found
      tags:
      -  'groups'
  /$schemagroups/{group-name}/schemas:
    parameters:
    - name: group-name
      in: path
      description: schema group
      required: true
      schema:
        type: string
    get:
      tags:
      - 'groups'
      summary: Get schemas for group name
      description: Returns schema by group name.
      operationId: getSchemasByGroup
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: string
        '404':
          description: Group not found
    delete:
      tags:
      - 'groups'
      summary: Deletes all schemas in group
      description: Deletes all schemas under specified group name.
      operationId: deleteSchemasByGroup
      responses:
        '204':
          description: OK no content
        '404':
          description: Group not found
  /$schemagroups/{group-name}/schemas/{schema-name}:
    parameters:
      - name: group-name
        in: path
        description: schema group
        required: true
        schema:
          type: string
      - name: schema-name
        in: path
        description: schema name
        required: true
        schema:
          type: string
    post:
      summary: Get schema GUID by schema content
      description: Get GUID for schema with matching byte content and serialization format.
      operationId: getGuidBySchemaContent
      parameters:
        - in: header
          name: X-Serialization
          schema:
            type: string
          required: true
      requestBody:
        description: schema content
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaBytePayload'
      responses:
        '200':
          $ref: '#/components/responses/SchemaIdResponse'
        '404':
          description: Matching schema not found
      tags:
        - 'runtime'
    put: 
      summary: Register schema
      description: >
        Register schema.
        If schema of specified name does not exist in specified group, schema is created at version 1.
        If schema of specified name exists already in specified group, schema is created at latest version + 1.
        If schema with identical content already exists, existing schema's GUID is returned. 
      operationId: createSchema
      parameters:
        - in: header
          name: X-Serialization
          schema:
            type: string
          required: true
      requestBody:
        description: schema content
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchemaBytePayload'
      responses:
        '200':
          $ref: '#/components/responses/SchemaIdResponse'
        '400': 
          description: Invalid request
      tags:
        - 'runtime'
    get:
      summary: Get latest version of schema
      description: Get latest version of schema. 
      operationId: getLatestSchema
      responses: 
        '200':
          $ref: '#/components/responses/SchemaBytePayloadResponse'
      tags:
        - 'schemas'
    delete:
      summary: Delete schema
      operationId: deleteSchema
      responses:
        '204':
          description: OK no content
        '404':
          description: Matching schema not found
      tags:
        - 'schemas'
  /$schemagroups/{group-name}/schemas/{schema-name}/versions:
    parameters:
      - name: group-name
        in: path
        description: schema group
        required: true
        schema:
          type: string
      - name: schema-name
        in: path
        description: schema name
        required: true
        schema:
          type: string
    get:
      summary: Get list of versions
      description: Get list of versions for specified schema
      operationId: getSchemaVersions
      responses:
        '200':
          description: OK
          headers: 
            X-Serialization:
              schema:
                type: string
              description: schema type
          content:
            application/json:
              schema:
                type: array
                items: 
                  type: integer
      tags:
        - 'schemas'
  /$schemagroups/{group-name}/schemas/{schema-name}/versions/{version-number}:
    parameters:
      - name: group-name
        in: path
        description: schema group
        required: true
        schema:
          type: string
      - name: schema-name
        in: path
        description: schema name
        required: true
        schema:
          type: string
      - name: version-number
        in: path
        description: version number
        required: true
        schema:
          type: integer
    get:
      summary: Get specified version of schema
      operationId: getSchemaVersion
      responses:
        '200':
          $ref: '#/components/responses/SchemaBytePayloadResponse'
        '404':
          description: Specified schema not found
      tags:
        - 'schemas'
    delete:
      summary: Delete specified version of schema
      operationId: deleteSchemaVersion
      responses:
        '204':
          description: OK no content
      tags:
        - 'schemas'

components: 
  schemas:
    SchemaId:
      type: object
      properties:
        id:
          type: string
    SchemaBytePayload:
      type: string
    SchemaGroup:
      type: object
      properties:
        name:
          type: string
        createdTimeUtc:
          type: string
          format: date-time
        updatedTimeUtc:
          type: string
          format: date-time
        serialization:
          type: string
        schemaCompatibility:
          type: integer
          description: schema compatibility mode enum, defined by support serialization format
        groupProperties:
          type: object
          additionalProperties:
            type: string
  responses:
    SchemaIdResponse:
      description: OK
      headers:
        Location:
          schema:
            type: string
        X-Serialization:
          schema:
            type: string
          description: schema type
        X-Schema-Id:
          schema:
            type: string
            format: uuid
          description: unique schema identifier
        X-Schema-Id-Location: 
          schema:
            type: string
            format: url
          description: location of schema resource
        X-Schema-Version:
          schema:
            type: integer
          description: version of returned schema
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SchemaId'
    SchemaBytePayloadResponse:
      description: OK
      headers: 
        Location:
          schema:
            type: string
        X-Serialization:
          schema:
            type: string
          description: schema type
        X-Schema-Id:
          schema:
            type: string
            format: uuid
          description: unique schema identifier
        X-Schema-Id-Location: 
          schema:
            type: string
            format: url
          description: location of schema resource
        X-Schema-Version:
          schema:
            type: integer
          description: version of returned schema
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SchemaBytePayload'