Extend preferredScheme to become baseUrl

[ErikWittern]

A recent issue (#96) lead to a pull request (#97) by @thejibz introducing the option to pass a preferredScheme, e.g., to specify whether to use http or https.

This option is relevant mostly in the context of Swagger definitions, though, and does not apply well to OAS 3 definitions: while the former define the base URL to call using schemes, host, and basePath fields, the latter use one of multiple Server Objects to do so. Thus, in the case of an OAS 3 definition being passed to OASGraph, some questions arise: what is the expected behavior if, let's say, preferredScheme is set to https but there are multiple server objects that define a URL with https? What if none of the server objects defines a URL with https? What if different operations in the OAS reference different server objects with different schemes?

Thinking about this, one compromise may be to extend the preferredScheme option by changing it into a baseUrl option. By providing a base URL to call, this option would encompass the functionality provided by preferredScheme in the context of a Swagger being passed to OASGraph. In addition, there could be simple semantics to also solve the issue of selecting a server object to use when an OAS 3 is passed to OASGraph: if present, OASGraph will always use the passed baseUrl for requests, and ignore server objects. This simplified behavior has, of course, the downside of not allowing to use different servers for different operations. However, if that is desired, I would argue that the OAS definition needs to be changed accordingly. A baseUrl option would still be valuable for development and testing purposes.

@thejibz and @Alan-Cha, what do you think?

[Alan-Cha]

I think the baseURL option is a really cool idea, especially for development and testing purposes. I also agree that preferredScheme needs a bit of rework as I'm trying to improve the functionality right now.

The issues that I am encountering stems from what you mentioned, that while Swagger makes explicit use of schemes, OAS only implies them. OAS does not guarantee that the URL stored in the server object contains a scheme. At least Swagger clarifies that If schemes are not specified, the scheme used to serve the API specification will be used for API calls. (source).

I still think preferredScheme has some advantages over baseURL. Namely, that it can dynamically use multiple servers. Perhaps we can bridge these two ideas with a preferredBaseURL option. We can add a force option to mimic the simplified behavior of baseURL. Alternatively, you can provide a list of URLs, all of which have a priority over other URLs in the order that they are provided. As OASGraph creates resolvers, it can take note of all available servers for any particular operation (definitely either locally or globally) and it can select whichever is most appropriate. Hopefully this solution will be closer to OAS 3 and provide the flexibility of both preferredScheme and baseURL.

[ErikWittern]

@Alan-Cha In the context of a Swagger definition, dynamically using multiple servers does not exist, as far as I know. There is only a single URL created from one of the schemes, the host, and the base path.

While OAS definitions allow using multiple servers, I think that the preferredScheme option would have unclear or hard to understand semantics. I am as of now against introducing a more complex preferredBaseURL option: OAS has a lot of flexibility when it comes to defining server URLs, and I don't think OASGraph should try to expose the same amount of flexibility. If that much flexibility is required, the OAS needs to be defined accordingly. The baseUrl option is merely a compromise, namely an easy way to (coarsely) override what's defined in an OAS, for example for testing / development.

[Alan-Cha]

Maybe I misspoke. By dynamically using multiple servers, I was still talking about in the OAS 3 context.

Hmmm, I see what you're saying but at the same time, GraphQL is suited for calling against different backends, using different protocols, and obtaining data from different sources so I don't see it as a far stretch to provide flexibility. In addition, we toyed around with the idea of forming GraphQL interfaces from from multiple APIs. I had this in mind when I proposed the idea of preferredBaseURL, trying to open the way towards this kind of ecosystem. Maybe this is a bit much though. After all, defining the OAS in the "right" way can resolve all of these issues.

[ErikWittern]

@Alan-Cha Exactly, we should leave such cases to the OAS definition! They provide a thought-through, iterated upon, and standardized (and thus also increasingly adopted) mechanism for such complex cases. So the support already exists.

The nature of a preferredX argument in OASGraph should not be to provide such capabilities, but to offer a simple way to override, in the context of development or testing.

[thejibz]

Hello guys,
I am happy to see that this mini-feature raises discussions !

I think we all agree that arbitraly taking the first server of the list is more of a workaround than a feature. So any way that allows to pick a server less arbitraly is good.

I see the concern about OAS v3 (list of base urls) vs OAS v2 (schemes). But in both case, what you get in OASGraph is a list of servers.

OAS v3 states:

In OpenAPI 3.0, you use the servers array to specify one or more base URLs for your API.

and

You can also have multiple servers, for example, production and sandbox

So I think that either:

• We count on the developper to be able to change the OAS and to provide only one server. Con: You don't always have the hand on the OAS file. Pro: We don't have to do anything.

• We let the developper to choose which baseUrl to use with a (preferred)baseUrl parameter. Con: More work on our part. Pro: You answer the need to generate a schema for a specific environment.

Both ways are not incompatibles though.

[ErikWittern]

@thejibz Thanks for chiming in!

I fully agree with your assessment, the two ways are not incompatible. I think we should offer a preferredBaseUrl or even simply baseUrl option (the latter has the advantage that the wording makes clear that ANY desired URL can be provided, not only one that is also defined in the OAS/Swagger).

Do you have concerns with replacing the preferredScheme option with a baseUrl option, though? It seems to me that a baseUrl option would encompass the functionality of the preferredScheme option, but maybe I am missing something?

[thejibz]

You're welcome !

+1 for the "baseURL" option. It offers even more control. I already had the case where I had to use an URL not listed in the OAS.

I will see what I can do ;)

[ErikWittern]

@thejibz Hey, I did not want to imply that you should have to take on this issue, of course. I merely wanted to ask for your input, because you raised the original issue and made the PR for the preferredScheme option. If you are willing to look into this, it would of course be highly appreciated! If not, Alan and I can also try to solve this. Just let us know sow we don't both work on it at the same time.

[thejibz]

@ErikWittern Ok, I must admit I wouldn't mind if you take on this ! I will stay around if you need my input ;)