Indicate the signature mechanism for the API

[earth2marsh]

As we relax the idea that paths must be unique, it can complicate the signature evaluation process. Consider adding a signature style as part of the info block, such as path+verb, action-header, or similar? (haven't thought this through fully, I just wanted to stub out the idea.)

[captainsafia]

I came across this discussion item while reasoning through what role operation IDs play in the v4 spec. Is the idea that these signatures would replace the existing operation ID property?

[earth2marsh]

We discussed signatures on today's call. Video will be posted here: #107 (comment) (and see also the doc mentioned in the comments)

[earth2marsh]

We're planning to pick up the signature topic again starting next week. The last time we discussed this, we ended up with this document. (It may have some useful concepts, but it was early, so it may also have some dead ends!)

[handrews]

In the last call, we talked about it being desirable that signatures could be statically analyzed for ambiguity, but also noted that:

1. We're not sure this is possible with the current path templating that is our 3.x equivalent of signatures
2. JSON Schema cannot be analyzed in this way, at least not in the general case

I think we should think about how we want signatures to appear in the ADA to help us figure this out.

The point of DOM and ADA is that tools (aside from those that parse to the DOM and/or map from DOM to ADA) will work with what the ADA exposes, not with the raw JSON/YAML. So we can build into ADA a certain amount of analysis, as long as the cost of the analysis is reasonable for all uses. In other words, if we can do some analysis that will help the vast majority of use cases, we should do that as part of the DOM to ADA mapping. But we should not standardize high-cost analysis that benefits only rare cases.

This will help us understand how much we can expect from static analysis, and give us a better cost-benefit calculation for figuring out if we're going too far with requirements (or not far enough).

One useful aspect of this exercise is that it would let us step back from specific choices. For example, should we use something similar to our extended URI Template-ish system, or standard RFC6570 URI Templates, or WHATWG URL Patterns, or... ??? Instead of debating that, we can come at it from the other end, by saying what ADA needs to be able to provide to tool developers, and then looking at which system or systems best supports that outcome.

Analyzing Path Templating

Let's start with our familiar 3.x path templating (and ignore parameters headers, bodies, etc.).

A path template can be broken up in two ways: Into path segments, and into literal vs variable sections. The most common use case is for each variable section to correspond to a single segment, but as recently discussed, this is not required.

So immediately we can come up with some things to decide regarding how ADA would expose path templates:

• Do we only expose literal vs variable, or do we want to indicate individual path segments, including noting whether a path segment is broken up into both literal and variable sections?
• What are the use cases that would help us decide this?
• For ambiguity that we can detect:
  • Do we require detection (what is the analysis cost?)
  • Does ambiguity result in an error?
  • If not, how is ambiguity indicated through ADA?

Note that we require concrete paths to take precedence over variables. Would it be easier to detect this if we broke things into segments? Would breaking into segments be problematic if we allow variables to expand to multiple segments, or would it be fine as long as everythign is processed left to right (or whatever direction the overall URL text is going)?

Some of these are easy to answer, others not so much, but I'll stop here for now to see what the reception is.