Accommodate legacy APIs by allowing query parameters in the path

[webron]

Issue by @earth2marsh

---

There are real APIs where a query string may determine the structure of the response, for example verbose=true, metadata=1, action=reboot.

However, Those cannot be expressed in Swagger 2.0 today because the path/verb maps onto a response model 1:1.

While it may be a bit of a kludge, consider a unique path where the query string is hard-wired into the path:
"path":"/me?metadata=1"

The order of the query params may not be determined in real situations, but for the purpose of defining methods in the spec, this may be an acceptable compromise to accommodate legacy services.

[webron]

Comment by @fehguy

---

Hi @earth2marsh I think the driver here will be the tooling. Having a query param in what should be a path might lead to nasty /me?metadata=1?foo=bar side effects.

[webron]

Comment by @earth2marsh

---

Yes, the tooling would have to check for the ? when building the query
string. But having a spec that can accommodate more APIs is a good thing,
even if the pattern itself is bad. #goingPostel

[webron]

Comment by @fehguy

---

Marsh I know you want to support all apis, but I worry that it would be at the expense of others. Perhaps you can use anchors? /me#hack1 I don't know how they would fit into the design but I know they're not explicitly forbidden

[webron]

Comment by @BSalita

---

Perhaps Swagger 3.0 can address such legacy APIs using conditionals.

"path" : "/me ? verbose==false && metadata==0"

[webron]

Comment by @maxlinc

---

@BSalita you'd need to write another specification just for how the conditionals are processed.

I still think the answer to those sorts of problems is still RFC 6570, because it's the closest thing to that specification.

At this point I think we should just ask tools to handle "path" as "the path portion of a URI template", and to consider an "x-query" extension for the "query portion of a URI template". I think it's better to have projects like swagger-js get started with basic URI template support before we try to extend it to cover query.

If they decide it isn't difficult to support it, here's how I'd expect it to work:

The default:

path: "/me?metadata=1"
# x-query: "{?parameters*}"

would produce: http://example.com/me?metadata=1?foo=oof&bar=rab&baz=zab, which has the problem @fehguy mentioned.

A simple override tells the tool how you want it handled:

path: "/me?metadata=1"
x-query: "{&parameters*}" # changed the prefix to &

That produces http://example.com/me?metadata=1&foo=oof&bar=rab&baz=zab, which is correct.

Even more complex patterns are possible, for example:

path: "/me?metadata=1"
x-query: "{&foo,bar}{;baz}"

Produces http://example.com/me?metadata=1&foo=oof&bar=rab;baz=zab.

The only thing I don't like about this is that path is a misnomer now. route would be a more appropriate name if it can include (some of) the query.

[earth2marsh]

Re-subscribing

[webron]

Parent: #574.

[antrix190]

Hey @webron I have something similar use case to handle, do we have a solution/work around to this issue yet?

[handrews]

This is too big of a change for 3.x, but Moonwalk's approach to operations might accommodate it.