Accommodate legacy APIs by allowing query parameters in the path
See original GitHub issueIssue 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:
- Created 9 years ago
- Reactions:8
- Comments:8 (7 by maintainers)
Top 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 >Top Related Medium Post
No results found
Top Related StackOverflow Question
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
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:
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:
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:
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.Hey @webron I have something similar use case to handle, do we have a solution/work around to this issue yet?