Identification of resources

[gentlewind]

By OAI spec, we identify resources by Path templates. But in implementation of REST APIs, we most often identify resources by URIs. Obviously, there are gaps among Path Templates, URIs (RFC7320) and URI Templates (RFC6570).

Per framework capability, it might be difficult to use OAI to document code-first REST APIs sometimes. For instance,

• Jersey requires to use path templates to design resource identifiers
• Spring MVC allows much more flexible resource identification by combination of path, query params and headers.

What's OAI's view on resource identification by documentation?

[darrelmiller]

You like picking the hard topics, don't you :-)

Personally, I would love to be able to describe a resource that is identified by an entire URI. I believe that sentiment is shared by the others in the TDC with the caveat of "not at any cost".

As you can see from this meta issue #574 we took a pretty big swing at addressing the many issues that are related to this topic. Somewhere in those issues (I searched but haven't found it yet) I make the assertion that I believe what we want is a deterministic algorithm for matching an instance URL to an operation description. Once you introduce optional path parameters, query parameters and discrimination by parameter value, it becomes challenging to identify an efficient algorithm.

However, if we could find a reliable, efficient way, to say this URI maps to this Operation without ambiguity, then I am convinced we could get it into the spec. My concern is that the only realistic way is with a "best fit" algorithm and I really don't want to go there unless all other options are exhausted.

[gentlewind]

Thanks for the link to these good discussions. I don't have deep research on the URI matching algorithms, but in practice, ant style path matching is a reliable approach, AntPathMatcher.

[handrews]

This wouldn't fit in 3.x, but might fit under Moonwalk's operation signatures principle. You might want to join discussions in that repo such as this one:

• Resource oriented sig-moonwalk#30