added callback specs

[sgalpha01]

I've added callback schema according OpenAPI v3 specs. Kindly review it and suggest necessary changes, if required.

[uniqueg]

Looks good but some points need some work, see comments.

[kellrott]

I'm not sure if this PR should be targeting develop. That is the current destination for TES 1.1. I don't think that callbacks will be part of 1.1. Maybe we should create a develop-1.2 branch to hold these more forward looking features.

[aniewielska]

@kellrott - think it can target develop, but will be merged after other changes get there.

[aniewielska]

BTW, we are quite inconsistent in the choice of camel vs snake case, but it has happened before this PR.

[uniqueg]

@aniewielska: While you are right about snake_case/camelCase inconsistencies in the TES specs, I don't see any new inconsistencies being introduced here. The PR follows usage in the current specs (e.g., schema names in camelCase, snake_case for schema properties). In the one case that is not already covered elsewhere in the specs (the name for the callback), it uses camelCase as does the exmaple in the OpenAPI 3.0 docs. I think this is reasonable.

[coverbeck]

This cool feature was mentioned at the GA4GH call, so I took a peek... I'm curious, how is authentication supposed to work for the callback url?

[patmagee]

github allows a simple password for webhooks but does not require it. I wonder if the callback should be an object instead of a single url:

"callback": {
  "url": "your url goes here",
  "headers": [
   { "key":"value"}
  ]
}

[aniewielska]

The idea here was not to put callback url behind extra authentication (the URL itself might be a secret?) and additionally advise consumers of the callback to verify the information by hitting the GET endpoint.

[patmagee]

@aniewielska thanks for the clarification. I wonder if it would still potentially make sense to make this an object to future proof in the case of wanting to add additional access mechanisms in the future

[coverbeck]

The idea here was not to put callback url behind extra authentication (the URL itself might be a secret?) and additionally advise consumers of the callback to verify the information by hitting the GET endpoint.

I think it would be nice to have your clarification in the spec.

I'm still slightly concerned about needing to expose a public callback url without auth, and I think Patrick's proposal addresses that, but I don't feel too strongly (and I'm not a reviewer anyway, just lurking :) ).

[uniqueg]

Good points here, thanks. Agree with future proofing by making it an object and extending the description to clarify that clients should verify the info from the callback and that the callback URL may include a secret

[coverbeck]

How will the the callback know which TES server is making the request? Is the callback expected to look at the Origin header (but I don't think that's guaranteed to be set)?