ServerApi: Propsal/clarification: prefix in URL

[nytamin]

I'd like to be able to implement an Ograf Server which exposes its OGraf API on urls with various prefixes.
For example, the API can be exposed on url johans-server.com/myPrefix/MyFolder/something-else/ograf/v1/**.

I'd like to hear your thoughts on this, and whether we should modify the API specification to explicitly support this?
eg, /graphics -> {prefix}/graphics.
Or is this implied to be acceptable already? (I'm a bit unsure what the OpenAPI spec allows and not.)

Another question to consider is should we require the url to be prefixed with /ograf/v1/**? (this might be useful in case we'd add breaking changes in the future).

[dvdeurse]

Reading the OpenAPI spec, what comes close to what you ask is the servers field (see https://learn.openapis.org/specification/servers.html). It allows you to specify a list of 'prefixes' in your OpenAPI definition. Typical use case is when you have multiple environments (like dev, staging, production) and you provide the base URL for each environment. A UI visualizing your OpenAPI spec can then easily switch between these servers. However, this solution is not feasible for the OGraf OpenAPI spec, because these prefixes are vendor-specific and can never be part of the actual OpenAPI definition in our case. So the real answer here is: is it possible to formally describe it with OpenAPI that various prefixes are allowed: no. Do we allow various prefixes: yes, but we need to explicitly mention this in plain normative text.

Regarding you proposal for adding the version inside the URL, it is a pattern that you see a lot but I'm personally not a big fan of it. The advantage of doing that, is that it is very clear for clients against which version they are talking to. The disadvantage is as follows. Implementations supporting multiple versions need to duplicate their endpoints, even if they are actually still doing exactly the same thing (I guess there will be some breaking changes, but not everything will be changed). This is needed if you want to keep supporting clients that are on older versions. If you don't introduce a version in your path, server implementations only need to implement the new things (on condition that this is possible). Besides, for the OGraf spec, we promised to keep it both backwards and forwards compatible. Why shouldn't we keep that promise for the Server API?

[rinode]

Besides, for the OGraf spec, we promised to keep it both backwards and forwards compatible. Why shouldn't we keep that promise for the Server API

I think this should be formalized if that's the case, as it's indeed very common to have API versioning in REST APIs. Guaranteeing bidirectional compatibility can elimitate the need for this... but it could become a maintenance burden down the road.

[nytamin]

Notes from Working Group 2026-03-18:

Yes, this should be allowed, let's update the specification to clarify that it is.