Use OpenAPI format for Resource Registration

[nynymike]

The OpenAPI specification is a standard for how to describe REST APIs.

If an OAI doc was registered for each resource, including the uma scopes, it has some benefits.

1. You have a much more descriptive base schema for describing API's.
2. You can define fewer parameters in the RR spec.
3. It is also more extensible without impacting the API.

For JSON rest API's, many developers are already creating OAI JSON, so it would be convenient to manage the UMA scope requirements, names, and descriptions there too.

For non-REST resources, I guess it's a little extra work.

[mrpotes]

The OAI spec is for describing HTTP operations. I'm not sure how this applies to the registration of resources with scopes at the AS. What is the AS supposed to do with that information when it has been given it?

[xmlgrrl]

Per UMA telecon 2017-03-09: The aim of Mike's proposal is to enable those documenting an API to capture, at the same time as they're thinking about describing the API for the audience of client devs, to capture related information. It consolidates what would have been two tasks into one. On the other hand, this rationale only applies if you're using OAI, and it also requires the AS to fetch a bunch of information that's not relevant to it, and deal with a lot of error conditions ditto. And what if it's not a REST API, but a file/folder paradigm with static resources or whatever?

Alternatively, what if the RS just used the OAI format as a common format somehow? Look at how long it took us to decide to add the "description" field last week. But then why not SCIM?? (Said in bitter jest...)

Positive registration is probably the bigger burden than the actual format being registered. We've now made it a little more implicit how a tightly coupled AS-RS relationship would be done (by doing away with the huge "extensibility profiles" infrastructure), but it's still possible to make more efficient through profiling a "different protocol than HTTP" for doing resource registration.

Swagger/OAI is used a lot for API documentation now, and there are a lot of tools for it, but we also have a rationale for all the pieces of the resource description document and scope description document now. It would perhaps be more attractive to extend OAI descriptors property to add scopes to them – but even then, the "customer" of that information is the client, not the AS.

Close this issue with no action but put on the extension label for future experimentation.