OAI
'*' as a resource not possible, but defined for OPTIONS
RFC7231 4.7.3 identifies the use of target resource '*' when using the OPTIONS method. However, per 3.1.0 RC0's requirement for patterned fields for the Path Item Object, the 'resource MUST begin with a slash '/'. At least for 3.1.0 RC0, it does not seem possible to articulate this.
It's a corner case. One might argue that since * is about the whole server, not the specific service, it might be out of scope for an API document. On the other hand, one might expect to be able to account for the entire functional surface of a web service using OpenAPI.
one might expect to be able to account for the entire functional surface of a web service using OpenAPI.
@cjaccino Does the same apply to the CONNECT method ? https://tools.ietf.org/html/rfc7231#section-4.3.6
I hadn't looked closely at CONNECT, but I believe that it, too, would be affected by the same constraint. It doesn't need '*'. Instead, according to 7231 section 4.3.6, it "MUST send the authority form of request-target"; https://tools.ietf.org/html/rfc7230#section-5.3.3.
Based on https://tools.ietf.org/html/rfc3986#section-3.2, Authority is made of userinfo, host, and port, with only host being required. But userinfo looks like it will be deprecated in the next HTTP semantics standard (https://tools.ietf.org/html/draft-ietf-httpbis-semantics-10#section-2.5.4). Whether it is better to look forward and impose the deprecation constraint vs. support flexibility of articulation isn't clear to me, but I believe OpenAPI has been heading in the direction of flexibility.
@cjaccino imho:
- on regular methods POST,PUT,PATCH,GET,HEAD the resource MUST still start with
/to avoid confusion - exceptions on other methods like OPTIONS could help when using OAS spec are used as a configuration tool for declaring acceptable requests
- I am not sure that utility methods like OPTIONS and CONNECT are useful in api design
My2¢,R
I, too, have little to offer for CONNECT today.
With OPTIONS and slash-leading endpoints, I see value in providing guidance on available media types for representations, as well as other constraints and features for that resource.
For OPTIONS and '*', I can imagine the scenario where an API Gateway might report its own capabilities or provide guidance for an SDK on how to configure itself. Perhaps an API gateway might report maximum payload size in requests as part of a bundle of information that could be normative for the host and all its APIs, but could be different for a different hosts with the same APIs.
Consider hybrid- and multi-cloud. Perhaps a client SDK must query * prior to interacting with the host's APIs due to nuanced differences between the corporate, premise-based API vs the cloud-based solution. In addition to payload sizes, known maximum durations for long request/response cycles, limits to concurrent connections, and similar information might be expressed. There may be other ways, but it seems like OPTIONS * may be the best place to express certain things, semantically speaking.
I could see two approaches here:
- Special-case
*as a "Path Template" - Allow defining an Operation Object on a Server Object
I lean more towards the special-case, as it would be syntactically unambiguous, and we are moving towards separating the shape and deployment of an API more cleanly. Putting an Operation Object in the Server Object would do the opposite.
Hmm... although now that I think of it, is * really better associated with deployments since it is server-wide? 🤔 The only reason to describe OPTIONS * is to describe the headers that might get sent back. In theory you can send a response body, but is there evidence that people do that?
@OAI/tsc review request: Is it worth figuring out where to put support for OPTIONS *, either in 3.2 or later in 3.x? If so, should this go with Paths (shape) or Server (deployment)? If not, let's close this as not planned.
I agree with Darrel's assessment in #2327 and suggest not adding this special case.
While it does seem that "*" is a valid resource in this special case, I feel like there are more important issues to tackle for 3.2. If someone felt strongly about this and wanted to make a proposal for describing this, I think we should review it, but otherwise we should put this in the backlog.
@ralfhandl Darrel's comment is a reason not to handle it in the Paths Object, but it could be handled in the Servers Object.
@mikekistler we decided recently that minor releases can be community-driven in terms of content (at least up to a point), so to me what you're saying is that yes, we'd accept a PR on this if someone did the work.
For those who might not follow my logic here, the question isn't "should we prioritize it?" It's "if someone comes by and wants to solve it, would we welcome that or not?" If not, we should own that decision, document it, and close the issue.
Adding operations to the Server Object seems overkill, given that OPTIONS * seems to be the only operation available "on the server".
I don't see other options and would rather postpone this issue.
Let's reconsider this special case once we've come up with a model for an HTTP request/response with sufficient semantics for APIs and see where it fits there.
@ralfhandl if we're postponing this based on modelng HTTP, then we should close this as "Moved to Moonwalk" (as we have everything else that is being addressed there, even if it might get backported to 3.x).
I agree with the general sentiment here, it's probably not useful to add as a special case in 3.2 and I will therefore close the issue as not planned.
