Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use OpenAPI format for Resource Registration #288

Open
nynymike opened this Issue Mar 2, 2017 · 2 comments

Comments

Projects
None yet
3 participants
@nynymike
Copy link

commented Mar 2, 2017

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

This comment has been minimized.

Copy link

commented Mar 8, 2017

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 xmlgrrl added the extension label Mar 13, 2017

@xmlgrrl

This comment has been minimized.

Copy link

commented Mar 13, 2017

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.

@xmlgrrl xmlgrrl closed this Mar 13, 2017

@xmlgrrl xmlgrrl removed the V2.0 label Mar 15, 2017

@xmlgrrl xmlgrrl reopened this Mar 15, 2017

@xmlgrrl xmlgrrl added fedauthz and removed rsrc-reg labels Jul 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.