WebHook Event Discrimination

[RobPhippen]

Summary

This issue proposes a mechanism to allow different logical events that occur on a single WebHooks callback API to be discriminated.

Relationship to other issues

This item is one of three split out from #716 as agreed at the OAI TDC on June 17th 2016.

The three items are;

• WebHook Event Subscription #735 , which covers webhook event subscription, but which is restricted to the case of modelling a single logical event stream for each physical callback API registered
• WebHook Event Discrimination #736 (this item), which can be considered to extend WebHook Event Subscription #735 to allow multiple logical event streams to be
• Asyncronous API callbacks #737 , which covers asynchronous callbacks

Objective of the proposal

This Issue extends #735 to allow discrimination between different logical event streams on the same physical callback URL. The rest of this document assumed that #735 has been read.

Proposed Syntax Updates

eventDiscriminator

This element extends the definition of x-event-streams to allow multiple logical event streams on the same physical callback URL. It extends the definition of 'parameterwithinx-event-streams` to add this element. It is only required where the 'discriminator' is contained within a header element. If the callback response body can be modelled via the existing swagger schema discriminators, then this can be used instead.

• eventDiscriminator:
  • Parameter: parameterName
  • This introduced to cope with cases where the webhooks callback URL can receive more than one type of event and the event type is conveyed in the header or query perameters. In these cases, the polymorphic Swagger discriminator cannot be used. The Parameter field specifies which parameter is used to discriminate between different events that may occur.
  • If eventDiscriminator is present, then the parameter named has a value equal to the event-id when that event occurs
  • If eventDiscriminator is absent, then event types are discriminated using the Swagger discriminator, as specified for the schema of the body parameter

Discriminator in a header: Swagger YAML snippet

We have chosen to illustrate example using github because it has a subcription API.

Please refer to the Github documentation on 'create a hook'
for further information on the API definition provided by Github for webhooks.

Please note that all elements beginning with x-github or x-hub are part of the Github API
specification, and do not form part of this proposal.
Finally, the Swagger below is not comprehensive - for example, not all objects are fully modeled.

paths:
  /repos/owner/repo/hooks:
    post:
      operationId: 'CreateHook'
      summary: Create a webhook in GITHUB
      description: |
        Call this API to create a new WebHook in Github
      parameters:
        - name: subscription
          in: body
          description: Details to subscribe for a callback on a given set of events
          required: true
          schema:
            $ref: '#/definitions/Subscription'
      tags:
        - Webhook
      responses:
        '202':
          description: Details of the subscription created to the webhook
          schema:
            $ref: '#/definitions/SubscriptionResponse'
      x-async-responses:
        - eventId: commentStream
          description: Comment event stream
          eventDiscriminator:
            parameter: X-GitHub-Event
          parameters:
            - name: comment
              in: body
              required: true
              schema:
                $ref: '#/definitions/comment'
            - name: X-GitHub-Event
              in: header
              type: string
            - name: X-GitHub-Delivery
              in: header
              type: string
            - name: X-Hub-Signature
              in: header
              type: string
        - event-id: deployment
          description: deployment event stream
          eventDiscriminator:
            parameter: X-GitHub-Event
          parameters:
            - name: deployment
              in: body
              required: true
              schema:
                $ref: '#/definitions/deployment'
            - name: X-GitHub-Event
              in: header
              type: string
            - name: X-GitHub-Delivery
              in: header
              type: string
            - name: X-Hub-Signature
              in: header
              type: string      

Discriminator in the message Body

In this example, the eventDiscriminator is absent, and event discrimination defaults to exploiting the discriminator defined in the schema for the body parameter.

x-event-streams:
  - event-id: Dog
    description: animal event stream
    parameters:
      - name: animal
        in: body
        required: true
        schema:
          $ref: '#/definitions/Dog'
 - event-id: Cat
    description: animal event stream
    parameters:
      - name: animal
        in: body
        required: true
        schema:
          $ref: '#/definitions/Cat'

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
  Dog:
    description: A representation of a dog
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize

[RobPhippen]

As discussed on OAI TDC
Check out #741 for potential solutions.

[fehguy]

Closing as #763 is merged