`callbacks` is a map of Callback Objects.... but why?

[webron]

The way the callbacks property is defined now, this is valid:

callbacks:
  callbacks1:
    "{myamazingexpressions}":
      PIO1:...
  callbacks2:
    "{myamazingexpressions}":
      PIO2:...

This means that you can define two different Callback Objects, each one having the same expression as a key, pointing to a different POI. That doesn't seem to make sense.

Perhaps callbacks should just be a Callback Object?

[darrelmiller]

I believe the idea of multiple distinct callback objects was introduced to support the notion of webhooks returning different "events". All of the callbacks might target the same client URL but the structure of the payload might be very different. Now that we have added support for JSON Schema oneOf it would be possible to do this with a single requestBody. However, if someone wanted to identify the event in a query parameter or HTTP header, it would not be possible using a single PathItemObject.

e.g.

callbacks:
  bankAccountDeposit:
    "{$request.body#/url}&eventType=deposit":
      post: ...
  bankAccountWithdrawal:
    "{$request.body#/url}&eventType=withdrawal":
      post: ...
  bankAccountOverdraft:
    "{$request.body#/url}&eventType=overdraft":
      post: ...

The question this raises for me is why not do this?

callbacks:
  bankAccountEvents:
    "{$request.body#/url}&eventType=deposit":
      post: ...
    "{$request.body#/url}&eventType=withdrawal":
      post: ...
    "{$request.body#/url}&eventType=overdraft":
      post: ...

This gets a bit more unclear if the event type was not in the query string but in a header or the body and of course the key is no longer unique, which is a bigger problem.

Is this better?

callbacks:
  bankAccountDeposit:
    targetUrl: "{$request.body#/url}&eventType=deposit":
    post: ...
  bankAccountWithdrawal:
    targetUrl: "{$request.body#/url}&eventType=withdrawal":
    post: ...
  bankAccountOverdraft:
    targetUrl: "{$request.body#/url}&eventType=overdraft":
    post: ...

This does mean that if a single subscription has multiple callback URLs provided by the consumer then it would need to define distinct callback objects. Which coincidentally is what we did in the workshop example.

      callbacks:
        heartbeat:
          '$request.query.heartbeat-url':
            post:
              requestBody:
                $ref: '#/components/requestBodies/heartbeatMessage'
              responses:
                '200':
                  description: Consumer acknowledged the callback   
        failed:
          '$response.body#/failedUrl':
            post:
              requestBody:
                $ref: '#/components/requestBodies/failedMessage'
              responses:
                '200':
                  description: Consumer acknowledged the callback   
        success:
          '$response.body#/successUrl':
            post:
              requestBody:
                $ref: '#/components/requestBodies/successMessage'
              responses:
                '200':
                  description: Consumer acknowledged the callback   

[fehguy]

It depends on where you're looking at callbacks.

In the components section, it doesn't matter if the callbacks have overlapping URLs! That's the consumer's problem. For description, it's fair for me to reference the callbacks from my operation like such:

paths:
  /test:
    get:
      ## blah blah
      callbacks:
        foo:
          $ref: '#/components/callbacks/bar

and in the components, nobody cares if the urls are overlapping. They're referenced by name.

Then you must mean inside the Operation object. In that case, the structure of the callbacks simply follows the same organization as in the components/callbacks. I didn't see any reason why to introduce a different one.

That said, it could change, but I think the goal was to make references easy. If it were a Map[], I don't believe it would work with multiple callbacks:

callbacks:
  $ref: '#/components/callbacks/foo'
  # oh snap!

vs. this:

callbacks:
  foo:
    $ref: '#/components/callbacks/foo'
  bar:
    $ref: '#/components/callbacks/bar'

Right?

[webron]

We're going leave this as-is, and see how the feature is used. Future versions may change the definition.