Avoid route conflict errors during API deployment due to common auth_call_back URLs when enabling security

[afsalthaj]

Multiple API definitions can be deployed to the same site, and certain routes may be enabled with security. This implies,
an additional route is internally available to facilitate oauth workflows. This auth-call-back URL is a user defined URL when updating their security schema. This works fine if there are multiple routes are enabled with the same call_back URLs within one API definition.

However, if users try to deploy another API definition with routes enabled with security using security schema with the same auth_call_back URL, then they end up getting route conflict error. Once again, this happens during API deployment and not when registering API definition.

This a valid production use case. i.e, users can deploy multiple definitions at various points in time into their domain as far as the routes don't conflict. They can end up using the same security schema across this API definition. A very simple example is, they can go ahead and update an existing API definition with updated routes, but with the same security schema and now they get a conflict error.

Possible best solution

Instead of adding call_back_url as an extra route in API definition (consisting of routes that uses security schema),
we create a separate internal API definition with call_back_urls.

This API definitions ID will be an ID corresponding to call back URL and not the security scheme id itself (security-schemes to call_back_url is (or can be) a many to one relation.

During deployment, if the API definition has a security schema in it, we choose to deploy this corresponding call_back_url API definition too. New call back URLs additions to this API definition will update its version.

Now when someone tries to create a new API definition making use of the same security scheme id, it is possible to check whether the corresponding call_back_url API definition is available.

During API deployment of a particular definition, we can see whether the corresponding call_back API definition draft is true, and if yes, we deploy it again, otherwise, skip it.

This way we have a API definition that consist of all the auth call back URLs for that host.