Allow defining multiple servers across multiple environments

[fariadev22]

Problem:
An API can have multiple servers involved e.g. the main server for API calls or servers related to OAuth 2.0 e.g. authorization server, token server, etc. Sometimes, some endpoints in the API may require a different server even though semantically they belong to the same API service.

And each of these servers can vary w.r.t. to the environment they are being called from e.g. the URLs of these servers can vary if the environment is production or sandbox.

Currently, OpenAPI allows defining multiple URLs across environments of a single server only. For OAuth 2.0 cases, since the OAuth servers are tied with the OAuth Flow Object as plain URLs, there is no way to specify their values across environments.

I work as an API specifications expert at APIMatic and we have encountered several users that run into such problems.

Suggested Solution
In APIMatic, we counter such cases by offering a server configuration vendor extension that allows you to specify values of multiple servers across multiple environments. There is a default environment and server to indicate what server will be used for all endpoints/OAuth by default unless they decide to override it.

{
  "x-server-configuration": {
    "default-environment": "production",
    "default-server": "server 1",
    "environments": [
      {
        "name": "production",
        "servers": [
          {
            "name": "server 1",
            "url": "https://example-prod-server-1.com"
          },
          {
            "name": "server 2",
            "url": "https://example-prod-server-2.com"
          }
        ]
      },
      {
        "name": "sandbox",
        "servers": [
          {
            "name": "server 1",
            "url": "https://example-sand-server-1.com"
          },
          {
            "name": "server 2",
            "url": "https://example-sand-server-2.com"
          }
        ]
      }
    ]
  }
}

Since each server has a name assigned to it, endpoints that require a different server (i.e. other than the default one) can override it by specifying its name explicitly.

{
   "get": {
      "description": "Get operation",
      "x-server-name": "server 1",
      "tags": [
         "Examples"
      ],
      "operationId": "Example",
      "produces": [
         "application/json"
      ],
      "parameters": [],
      "responses": {
         "200": {
            "description": ""
         }
      }
   }
}

In my opinion, having something similar in OpenAPI v4 could be quite useful.

[darrelmiller]

I'm not sure I follow what you mean by OpenAPI only allows defining environments across a single server. I like the idea of just using a named reference for redefining the server at the operation level. Have you seen this proposal? #50 It might help with your scenario

[handrews]

@fariadev22 does the refactored deployments proposal address your use case?

[fariadev22]

@handrews for the most part, yes. But it doesn't cover how multiple servers (dev, prod) for OAuth URL cases will be handled since I don't see any link between a security scheme definition and the deployments.

[ralfhandl]

Wouldn't that be this part of the diagram, once the details of a SecurityRequirement are filled in?

classDiagram
  class Deployment {
    title: string
    location: string
    clientRegistrationUrl: string
    apiDescriptionUrl: string
  }

  
  Deployment "0" --> "0..*" SecurityRequirement:security  


  class SecurityRequirement {

  }

Loading

[fariadev22]

@ralfhandl the example below the diagram in the same document shows Security Requirement defined as security which seems to have the same structure as is still being used in OpenAPI 3.x. That is the reason why I mentioned the need to have a link in "Security Schemes" instead where the security scheme is actually defined.

OpenApi: 4.0.0
namespace: self
deployments:
    default: 
      title: "prod - ca"
      location: https://api.example.ca
      security:
          - basic: []
      clientRegistrationUrl: "https://developers.example.com/catalog/accounts" # optional, identifies where credentials may be obtained
      apiPaths: self  // Do we really need this or can it be implicit?

[handrews]

@fariadev22 I had interpreted that as using the basic security scheme, with something of an inline or implicit security requirement, since the example doesn't define security schemes separately. But I'm really not sure. @darrelmiller what was the intent here?