Expressing responses to requests which paths are the URL of a resource

[ericmorand]

Sorry for the probably confusing title - please feel free to propose some better wording.

In a REST-compliant world, there is no need for the concept of a discrete resource identifier. To be more accurate, the URL of the resource is its canonical identifier, and there is no need for something else (like an id attribute). This URL is returned in the response to the request that creates a new resource - usually in the Location header but REST doesn't enforce that.

It makes expressing REST APIs with OpenAPI a bit confusing and awkward. For example, expressing the following endpoint to get an existing resource is less than ideal:

path: "/foo/{fooId}"

The reason is that there is not guarantee that this is the path of the resource identified by fooId. It may be but it may also be something else since the only guaranteed path to a resource is the one that was returned when the resource was created.

For example, foo#1 could totally we available at foo/1 while foo#2 could be available at resources/foo/2 and it would be perfectly correct in a REST compliant world. The first URL is the one that was returned when foo#1 was created, and the second one was the URL returned when foo#2 was created. This is totally legit as long as each URL allows to reach their corresponding resource, forever.

Still, the response structure for these two URLs is the same: they are both resources of type foo, and the response reflects that.

With OpenAPI, it means that we must document each of these paths, even though they are by no mean contractual. The only contractual thing is that the URL returned on successful creation is the URL to the newly created resource.

This gets even more impractical when we consider the other verbs that apply to the same URL (DELETE, PUT...) and the URLs that are built from the URL (like /foo/1/email) that also need to be documented separately for each variant - even though it is not necessary.

One of my coworkers proposed that we just use {fooURL} as path, and declare fooURL in the list of parameters, but it does not work because OpenAPI enforces that paths start with a / - and also consider that paths are always relative to an hypothetical API Server URL.

The only approach that allows for the OpenAPI document to validate is to use /{fooURL} as path which is wrong: the resource URL may be absolute, which would lead to an incorrect URL at runtime. Enforcing that the URL of a resource is relative and does not start with a / is a very bold move that defeat the whole purpose of having the server assign an URL to the resource it is responsible for creating - basically REST.

Is it possible to overcome this problem with the current specification? Can we express responses without having to enforce request's path?

And what is the plan - if any - to take this issue into consideration in the next iteration of the specification?

[handrews]

@ericmorand The OpenAPI Specification is fundamentally a static description of possible API interfaces, rather than a contractual definition. A described endpoint may still return a 404 even if no such response is explicitly described, for example. Regardless of API design intent, this incompleteness property is necessary as intermediaries can respond with unanticipated errors. Similarly, un-described endpoints may exist and still be usable, albeit without the support of the OpenAPI description information.

So there are really two options here:

1. Describe all of the possible endpoint path templates, knowing that not all of them will be usable for all resources that might appear to fit them
2. Describe only those endpoints needed to get started, and document (in text/markdown) that additional endpoints are intended to be discovered at runtime

The Location and/or Content-Location headers can be described and documented as required in API responses. Those headers have well-defined semantics, so documenting a required Location in a 201 response would convey what you are describing here (for less-standard locations for returning a created URI, you will need to be more explicit in your descriptive fields).

OAS 3.2 also provides full support for modeling the HTTP Link header, which could do a lot of what you want here.

In all OAS 3.x versions, the Link Object (which is somewhat confusingly not directly related to the Link header) can be used to do a bit more mapping of responses to further requests, although the Arazzo specification might be a better approach depending on your use case.

---

I realize this is likely unsatisfying, but I am not aware of a significant demand for the sort of more-or-less free-form URI determination at runtime combined with static description by OpenAPI. To get something that directly supports such a pattern into the OAS, you would need to show that it is sufficiently widespread to be worth the burden on tool implementors. It's not clear to me that that is the case.