Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Accommodate legacy APIs by allowing query parameters in the path

See original GitHub issue

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.

Issue Analytics

  • State:open
  • Created 9 years ago
  • Reactions:8
  • Comments:8 (7 by maintainers)

github_iconTop GitHub Comments

webroncommented, Sep 21, 2014

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:, 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, which is correct.

Even more complex patterns are possible, for example:

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


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.

antrix190commented, Nov 18, 2020

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

Read more comments on GitHub >

github_iconTop Results From Across the Web

How to define different query parameters for same path in ...
Accommodate legacy APIs by allowing query parameters in the path ... you can have two definitions to the same path by adding a...
Read more >
REST API Design Best Practices for Parameter and Query ...
Many APIs work this way. Every endpoint uses POST and all parameters are in the body. This is especially true in legacy APIs...
Read more >
OData Client operation (V 4.0)
Unique parameters are required at run-time to request data. Review the topic about parameter values to understand how to statically or dynamically define ......
Read more >
REST API Developer Guide
Salesforce CDP Query Profile Parameters . ... REST API supports OAuth 2.0 (an open protocol to allow secure API ... the request parameter...
Read more >
Legacy SQL Functions and Operators | BigQuery - Google Cloud
Returns the original string with all characters in upper case. Table wildcard functions. TABLE_DATE_RANGE(), Queries multiple daily tables that span a date ...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Post

No results found

github_iconTop Related Hashnode Post

No results found