Handle `servers` variable params

[DmitryAnansky]

Hi Everyone,

I encountered a scenario that isn't explicitly covered in the documentation, and I'm hoping you can clarify it for me. It is possible to define server variables in OpenAPI like this:

servers:
  - url: 'https://api-url.example.com/organizations/{organizationId}'
    description: api server
    variables:
      organizationId:
        default: unknown
        description: >-
          Unique organization identifier.

My confusion arises from how to pass this organizationId to the step parameters. My assumption was to pass it as a parameter like this:

    steps:
      - stepId: getData
        operationId: GetData
        parameters:
          - in: path
            name: organizationId
            value: someOrg

However, it seems that this organizationId parameter doesn't actually belong to the parameters in the path, but rather to the server variables. Please let me know if you have some configuration in mind, maybe you already discussed it before.

Looking forward to your reply, Thank you.

[jeremyfiel]

is it fair to assume a server url and path url would be combined into one for the purposes of the workflow? In that case, it would still pass as a path variable and should be substituted at runtime.

[RomanHotsiy]

But how about the server variables which are not path:

servers:
  - url: 'https://{organizationId}.example.com'
    description: api server
    variables:
      organizationId:
        default: unknown
        description: >-
          Unique organization identifier.

[jeremyfiel]

oh that's a good question, we don't have any enum for a server variable because parameter is taken from the OAS definition, body, cookie, path, query, header, only.

I think you can use the reusable object for this use case and use an expression

version is the variable name. the servers index can be modified in the expression if more than one server exists

reference: '$.servers[0].variables.version.default'
value: <new value>

[jeremyfiel]

actually, this may not work because the ABNF in the spec doesn't cover the servers array. i may be interpreting it incorrectly

https://spec.openapis.org/arazzo/v1.0.0#runtime-expressions

[RomanHotsiy]

I'm sure it's not covered. For now we'll just use path parameters in our implementation but would be great to cover it in the future versions of arazzo.

[frankkilcommins]

Hi folks,

Apologies in delayed response here. As @RomanHotsiy hints to, this is not covered by Arazzo currently. At the moment it's left up to the runtime process (e.g. what's invoking the Arazzo Document) to determine what target host to call.

As different OADs within the sourceDescriptions can have different server variable constructs, I do think that extending the Parameters Object to cover in: server might be a solid way forward.

This is a good candidate for 1.1.0

[adamaltman]

There can also be multiple servers defined in a single OAD. It seems like there should be some way for the user to indicate (via inputs maybe) which server (and if there are variables, which values) to use.