Do server variables allow unencoded slashes?

[hkosova]

This is somewhat related to #2204 and #2218. It's been clarified that path parameters don't allow unescaped slashes, but what about server variables?

Consider this example:

servers:
  - url: "https://example.com/{subpath}reports/"
    variables:
      subpath:
        default: ''
        enum:
          - ''
          - 'abc/123/'
          - 'abc/456/'

Are these valid values for a server variable?
If yes - what is the resulting server URL for subpath=abc/123/? --

https://example.com/abc/123/reports/
 or
https://example.com/abc%2F123%2Freports/

In other words, is the example above a proper way to vary subpaths using server variables, or should this example be rewritten as follows? --

servers:
  - url: "https://api.example.com/reports/"
  - url: "https://api.example.com/abc/{id}/reports/"
    variables:
      id:
        default: ''
        enum:
          - '123'
          - '456'

[earth2marsh]

My preference would be to align with the path restrictions and disallow forward slashes. That approach seems more consistent, and the implications of the Helen's rewritten example seem perfectly acceptable to me. Phil's language from #2218 seems appropriate here, too:

The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by [RFC3986](https://tools.ietf.org/html/rfc3986#section-3): forward slashes (`/`), question marks (`?`), or hashes (`#`).

[MikeRalphson]

While I see and respect the argument for consistency, in the case of serversthe rationale for not allowing unescaped slashes as in paths keys doesn't seem to apply.

Here one server of several is selected to be used, unlike paths which may need to be considered together. I don't think any ambiguity is introduced by allowing unescaped slashes in servers urls.

[DavidBiesack]

I concur with Mike - in my mind, these are not path variables, they are template variables

The value is used for substitution in the server's URL template.

[earth2marsh]

Are there real world examples that show why allowing slashes would help? Has this been a complaint in the past? I cannot think of any API whose server location depends on representing something like a nested folder structure. Without that, I still prefer the more constrained, consistent approach, but I'm not strongly opposed either way, tbh.

[awwright]

Many years ago, I was writing a program that let you look up various information on a user given their username. Obviously, characters in the nickname that were outside the "reserved" set had to be URL encoded.

I was quite disappointed that the platform I was using had difficulty using %2F to encode a slash in a nickname. It did not appear to make a distinction between the encoded and literal / forms. It turns out, this behavior is technically incorrect.

RFC 3986 specifies how encoding works not just mechanically, but semantically:

The purpose of reserved characters is to provide a set of delimiting characters that are distinguishable from other data within a URI.

URIs that differ in the replacement of a reserved character with its corresponding percent-encoded octet are not equivalent.

URI producing applications should percent-encode data octets that correspond to characters in the reserved set unless these characters are specifically allowed by the URI scheme to represent data in that component.

---

To answer OP, I would expect:

Are these valid values for a server variable?

Yes

If yes - what is the resulting server URL for subpath=abc/123/? --

https://example.com/abc%2F123%2Freports/

Note how the slashes are URL encoded in the absence of the + modifier.

[darrelmiller]

The limitation on path templates is to prevent ambiguous resolution of operations. e.g.

/reports/foo/bar
/reports/{someparam}    where someparam = foo/bar

In the case of server variables mapping to a different server URI does not have significant consequences. However preventing a a forward slash in a server variable would prevent multi-segment variable values. e.g.

/{tenantName}/mysaasresource

/cocacola/us/mysaasresource
/cocacola/uk/mysaasresource

If forward slashes are not intended to create path segments in the URL then the need to be a percent encoded.

Nobody raised an objection to this in the TSC call because Marsh was missing :-) Hence the current wording of the spec is sufficient.

[awwright]

then they need to be a percent encoded

By who?

[darrelmiller]

@awwright By the tooling providing the parameter value. The reference you quoted in RFC3986 is a good one and might warrant us adding words that indicate a server variable should not be treated as a "data octet" but as a literal portion of the URL.