discovery.yaml

openapi: '3.0.2'
info:
  title: CloudEvents discovery API
  description: CloudEvents discovery API specification according to [Discovery - Version 0.1-wip](https://github.com/cloudevents/spec/blob/main/discovery/spec.md#service).
  version: '0.1-WIP'
servers:
  - url: https://api.cloudevents.io/test/v0.1
paths:
  /services:
    get:
      operationId: getServices
      description: Get an optionally filtered collection of the Services known by this discovery end point
      parameters:
       - in: query
         name: name
         description: The name of the service to be returned
         required: false
         schema:
           $ref: '#/components/schemas/service/properties/name'
      responses:
        '200':
          description: A list of services (optionally matching the query parameter)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/services'
    post:
      operationId: postServices
      requestBody:
        $ref: '#/components/requestBodies/servicespostrequest'
      responses:
        '200':
          $ref: '#/components/responses/servicespostresponse'
        '400':
          description: Bad Request - constraint failure
        '409':
          description: Conflict - epoch not greater
    delete:
      operationId: deleteServices
      requestBody:
        $ref: '#/components/requestBodies/servicesdeleterequest'
      responses:
        '200':
          $ref: '#/components/responses/servicesdeleteresponse'
        '400':
          description: Bad Request - constraint failure
        '404':
          description: Not Found
        '409':
          description: Conflict - epoch not greater
  /services/{id}:
    get:
      operationId: getService
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: The corresponding service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service'
        '404':
          description: Not Found
    put:
      operationId: putService
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        $ref: '#/components/requestBodies/serviceputrequest'
      responses:
        '200':
          $ref: '#/components/responses/serviceputresponse'
        '400':
          description: Bad Request - constraint failure
        '404':
          description: Not Found
        '409':
          description: Conflict - epoch not greater
    delete:
      operationId: deleteService
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        $ref: '#/components/requestBodies/servicedeleterequest'
      responses:
        '200':
          $ref: '#/components/responses/servicedeleteresponse'
        '400':
          description: Bad Request - constraint failure
        '404':
          description: Not Found
        '409':
          description: Conflict - epoch not greater
components:
  parameters:
    id:
      in: path
      name: id
      description: The id of the service
      required: true
      schema:
        $ref: '#/components/schemas/service/properties/id'
  requestBodies:
    servicespostrequest:
      description: A request to create or update the discovery endpoint's collection of services with the given services
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/services'
    servicesdeleterequest:
      description: A request to remove the given services from the discovery endpoint's collection of services
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serviceinstances'
    serviceputrequest:
      description: A request to create or update the discovery endpoint's collection of services with the given service
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/service'
    servicedeleterequest:
      description: A request to remove the given service from the discovery endpoint's collection of services
      required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serviceinstance'
  responses:
    servicespostresponse:
      description: A list of the resulting Service values resulting from processing the request, in the same order as in the request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/services'
    servicesdeleteresponse:
      description: A list of the Services that were deleted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/services'
    serviceputresponse:
      description: A Service Instance referencing the updated Service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/service'
    servicedeleteresponse:
      description: The Service that was deleted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/service'
  schemas:
    eventtype:
      type: object
      properties:
        type:
          type: string
          description: CloudEvents type attribute
          example: com.github.pull.create, com.example.object.delete.v2
        description:
          type: string
          description: Human readable description
        dataschema:
          type: string
          description: CloudEvents datacontenttype attribute. Indicating how the data attribute of subscribed events will be encoded
        dataschematype:
          type: string
          description: If using dataschemacontent for inline schema storage, the dataschematype indicates the type of schema represented there
        dataschemacontent:
          type: string
          description: An inline representation of the schema of the data attribute encoding mechanism. This is an alternative to using the dataschema attribute
        sourcetemplate:
          type: string
          description: A URI Template according to RFC 6570 that defines how the source attribute will be generated
          example: "http://blob.store/{bucket}"
        extensions:
          type: array
          description: An array or CloudEvents Extension Context Attributes that are used for this event type
          items:
            type: object
            properties:
              name:
                type: string
                description: The CloudEvents context attribute name used by this extension
              type:
                type: string
                description: The data type of the extension attribute
              specurl:
                type: string
                description: An attribute pointing to the specification that defines the extension
          example: '{ "name": "dataref", "type": "URI-reference", "specurl": "https://github.com/cloudevents/spec/blob/main/extensions/dataref.md" }'
    eventtypes:
      type: array
      items:
        $ref: '#/components/schemas/eventtype'
    serviceinstance:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this Service. This value MUST be globally unique
          format: uuid
          example: bf5ff5cc-d059-4c79-a89a-2513e45a1340
        epoch:
          type: integer
          description: The Discovery Endpoint's epoch value for this Service Entry
          format: int64
          example: 42
    serviceinstances:
      type: array
      items:
        $ref: '#/components/schemas/serviceinstance'
    service:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/serviceinstance/properties/id'
        epoch:
          $ref: '#/components/schemas/serviceinstance/properties/epoch'
        name:
          type: string
          description: A unique identifier for this Service
          example: my storage service
        url:
          type: string
          description: A URL that references this Service. This value MUST be usable in subsequent requests, by authorized clients, to retrieve this Service entity
          example: http://example.com/services/bf5ff5cc-d059-4c79-a89a-2513e45a1340
        description:
          type: string
          description: Human readable description
        docsurl:
          type: string
          description: Absolute URL that provides a link to additional documentation about the service. This is intended for a developer to use in order to learn more about this service's events produced
          example: http://cloud.example.com/docs/blobstorage
        specversions:
          type: array
          description: CloudEvents specversions that can be used for events published for this service
          items:
            type: string
            description: version
          example: '[ "1.0" ]'
        subscriptionurl:
          type: string
          description: An absolute URL indicating where CloudSubscriptions subscribe API calls MUST be sent to
          format: url
        subscriptionconfig:
          type: object
          description: "A map indicating supported options for the config parameter for the CloudSubscriptions subscribe() API call. Keys are the name of keys in the allowed config map, the values indicate the type of that parameter, confirming to the CloudEvents type system. TODO: Needs resolution with CloudSubscriptions API"
          additionalProperties:
            type: string
        subscriptiondialects:
          type: array
          description: Filter dialects that can be used in subscriptions for this service
          items:
            type: string
            description: filter dialect
          example: '[ "basic" ]'
        authscope:
          type: string
          description: Authorization scope needed for creating subscriptions. The actual meaning of this field is determined on a per-service basis
          example: storage.read
        protocols:
          type: array
          description: This field describes the different values that might be passed in the protocol field of the CloudSubscriptions API. The protocols with existing CloudEvents bindings are identified as AMQP, MQTT3, MQTT5, HTTP, KAFKA, and NATS. An implementation MAY add support for further protocols. All services MUST support at least one delivery protocol, and MAY support additional protocols
          items:
            type: string
            description: protocol
          example: '[ "HTTP", "AMQP", "KAFKA" ]'
        events:
          $ref: '#/components/schemas/eventtypes'
    services:
      type: array
      items:
        $ref: '#/components/schemas/service'
    # This schema is returned as the `dataschemacontent` when discovery endpoints offer themselves as Service entities
    change:
      type: object
      oneOf:
        - $ref: '#/components/schemas/changeservicespost'
        - $ref: '#/components/schemas/changeserviceput'
        - $ref: '#/components/schemas/changeservicesdelete'
        - $ref: '#/components/schemas/changeservicedelete'
    changes:
      type: array
      items:
        $ref: '#/components/schemas/change'
    changepost:
      type: string
      enum:
        - POST
    changeput:
      type: string
      enum:
        - PUT
    changedelete:
      type: string
      enum:
        - DELETE
    changeservicespath:
      type: string
      pattern: ^\/services(\/){0,1}$
    changeservicepath:
      type: string
      pattern: ^\/services(\/[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}){0,1}$
    changeservicespost:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/changepost'
        path:
          $ref: '#/components/schemas/changeservicespath'
        request:
          $ref: '#/components/requestBodies/servicespostrequest'
        response:
          $ref: '#/components/responses/servicespostresponse'
      required: [operation, path, request, response]
    changeservicesdelete:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/changedelete'
        path:
          $ref: '#/components/schemas/changeservicespath'
        request:
          $ref: '#/components/requestBodies/servicesdeleterequest'
        response:
          $ref: '#/components/responses/servicesdeleteresponse'
      required: [operation, path, request, response]
    changeserviceput:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/changeput'
        path:
          $ref: '#/components/schemas/changeservicepath'
        request:
          $ref: '#/components/requestBodies/serviceputrequest'
        response:
          $ref: '#/components/responses/serviceputresponse'
      required: [operation, path, request, response]
    changeservicedelete:
      type: object
      properties:
        operation:
          $ref: '#/components/schemas/changedelete'
        path:
          $ref: '#/components/schemas/changeservicepath'
        request:
          $ref: '#/components/requestBodies/servicedeleterequest'
        response:
          $ref: '#/components/responses/servicedeleteresponse'
      required: [operation, path, request, response]