Specification Does Not Allow for Host Name Changes

[lcrabb]

We use an architecture which does not fix the host name for various resources. The API for this architecture uses hypermedia to inform clients of resource locations. While the proposed mechanism for handling hypermedia implementations (see #742) is useful, it does not allow for adjustment of the host name. This is a key issue for us and may drive us away from the specification if we cannot find a solution.

[DavidBiesack]

I'm curious - are the operations performed on these different hosts the same across hosts, or does each host support a separate (non-overlapping) set of resources and/or operations? That is, can your system be described as multiple independent but collaborating APIs? Or multiple APIs which share a common core set of operations/resources but which then specialize based on the resource locations? Is the primary limitation that the link object uses a operationId that must exist in the current OAS docuemnt?

[darrelmiller]

@DavidBiesack the link object isn't required to use operationId to link to existing operations. In fact it doesn't even need to point to a described operation

@lcrabb The link object isn't primarily directed at people building hypermedia APIs. Having said, if you did want to statically describe the links that might appear in a response, then you could do that. If you want to change the host name then you are now allowed to do that at the path item or operation level.

[lcrabb]

@DavidBiesack in answer to your question, the operations/resources are the same but the host and path can change and cannot be predicted by the client.

@darrelmiller is it possible to use variable substitution to accommodate the use of a different host name for different responses?

[darrelmiller]

@lcrabb Not yet. There is an issue open for it #169 though

[lcrabb]

@darrelmiller Depending on how #169 is resolved that could solve the problem. For our use case, it would require variable substitution as described in #742.

[ePaul]

@lcrabb In #577 I proposed a way of describing operations without fixing the paths (including host name). It didn't yet find many friends with the powers-that-be here, though.

[lcrabb]

@ePaul Thanks for the reference. I need to study and better understand the proposal. I've become comfortable with #742 with the exception of the hostname limitation.

Also, some concern with limitations of variable substitution where payloads can be binary and links are communicated in headers. This may limit ability to parse specific elements (such as hostname).

[fehguy]

We do support multiple hosts per document and have provided a design-time mechanism to override them. See here for details and feel free to re-open with questions:

https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#server-object