api-blueprint
api-blueprint copied to clipboard
apiaryio
Response based on parameter values
Hi
I don't know if it is already possible as i could not find something in the examples/documentation. Can a response be conditional based on a parameter value in the request? e.g.
- Parameters
- where (string, optional) ...
- Values
-
Name eq 'My Name' -
Name ne 'My Name'
-
- Values
- where (string, optional) ...
- Response 200 (application/json) if
Name eq 'My Name'response json x - Response 200 (application/json) if
Name ne 'My Name'response json y
If it is not possible this would be a nice feature.
Cheers!
Hey @martijnschouwe
thanks for sharing the idea! Actually something very similar is planned as it is much needed for full support of the testing #21 (also refer to #40 )
Like your idea by appending if ... after the response definition, not sure how it would work for more thank one or two parameters tho.
I am thinking more like pairing request with responses to form a transaction pair / examples.
Something along these lines:
# Resource [/resource/{param1}/{?param2,param3}]
+ Parameters
+ param1 ... bla
+ param2 ... bla bla
+ param3 ... bla bla bla
## Retrieve [GET]
+ Request 1
+ Parameters
+ param1: 42
+ param2: A
+ param3: X
+ Response 200
...
Thoughts?
@zdne Pairing is always a nice way indeed as it is clear at one glance rather then to interpret a if statement, good one! :+1:
Ditto, we had to put quite a bit of JavaScript hackery to work around this feature deficiency.
... which will likely break as soon as we upgrade versions :/
@sergiofbsilva @Gaffney Could you please elaborate a bit on our use cases? Why do you need it and / or what JS hackery you had to use?
Also is the proposed syntax OK (feel free to throw in anything else)?
Hey @zdne,
tl;dr
#js-hacks #multiple-examples #custom-urls
Syntax looks fine.
I can give you access to the aforementioned API documentation if you email me.
Summary of some issues we ran into (most of which are related to this one) plus our work-arounds below:
- We ended up hosting CORS-enabled assets to inject sections of the page so the apiary.apib wasn’t cluttered with ugly HTML. This relates to this issue.
- Our main resource is polymorphic in both input and output, which naturally results in having multiple use cases. When we attempted to add multiple requests and responses directly from the .apib file, Apiary listed all requests first and then all responses. To work around this, we interleave "stories" (example descriptions) and URL-modified requests with the responses.
- Our query parameter syntax does not follow that of a typical URI, and Apiary is currently not flexible enough to handle this. For example, Apiary’s “explode modifier” is of no use to us as we use semicolon-delimited arrays instead of the common repeating parameter
x=v1&x=v2&...&x=nformat. Query parameters may also have additional attributes, specified after a space (e.g.groupings=location;year+verbose=true). Together these customizations allow for concise, clean-looking JSON-less/flat queries. - "Try me" only works for 1:1 request/response resource examples, so we replaced all occurrences of the generated mock domain with some bogus domain, and removed the “Try me” button.
@Gaffney
When we attempted to add multiple requests and responses directly from the .apib file, Apiary listed all requests first and then all responses.
I believe this should be now fixed in Apiary.
Apiary’s “explode modifier” is of no use to us as we use semicolon-delimited arrays instead of the common repeating parameter x=v1&x=v2&...&x=n format.
Can you elaborate on this? I am trying to find out whether this is the limitation of API Blueprint or Apiary (or both)
Query parameters may also have additional attributes, specified after a space (e.g. groupings=location;year+verbose=true).
After a space? Again can you give me an example?
Thanks!
Apiary’s “explode modifier” is of no use to us as we use semicolon-delimited arrays instead of the common repeating parameter x=v1&x=v2&...&x=n format.
For example, using commas, user_ids=1,2,3,4 instead of user_ids=1&user_ids=2&user_ids=3&user_ids=4
After a space? Again can you give me an example?
The above groupings=location;year+verbose=true was an example (+ is a url-encoded space). There are many other possible scenarios, such as the query structure the Facebook's Graph API uses, which would not fit into the Apiary model.
This will be a great feature but will it cover also POST requests, i.e. so that it would be possible to define different responses on the basis of the POST payload?
Hey @BlackMan82, this is currently in the development as #25 – you will be able to describe request (or any other) attributes and the follow with appropriate response.
What @arekkas proposes here:
## The translation API [/i18n/{id}{?locale}]
+ Parameters
+ locale (required, string, `de_DE`)
+ id (required, int, 1)
### Retrieves a translation [GET]
+ Request Volkswagen
+ Parameters
+ locale: de_DE
+ id: 1
+ Response 200 (application/json)
{ "message": "Volkswagen" }
+ Request Ford
+ Parameters
+ locale: de_DE
+ id: 2
+ Response 200 (application/json)
{ "message": "Ford" }
Is another good example how this should be implemented
+1 on this, seems like a very obvious missing feature! Let me know what I can do to help get it working.
Updated proposal (to latest URI params syntax):
# Collection [/collection{?limit}]
## List [GET]
+ Parameters
+ limit (number) - Maximum number of entries returned
+ Request Limit to One Entry
+ Parameters
+ limit: 1
+ Response 200 (application/json)
[ {} ]
+ Request Limit to Three Entries
+ Parameters
+ limit: 3
+ Response 200 (application/json)
[ {}, {}, {} ]
Please let me know if this will work for you @netmilk
@zdne Thank you for the proposal! It perfectly works for me for adding or changing parameters and its values. More general question is, and maybe it's more MSON related, is how to dereference (exclude,remove) some property.
So, related to your example, question is how to remove the limit parameter from the Request Limit to Three Entries to not be sent in the URI even if it is discussed under the Action section.
+1 Would be super helpful to have this feature. In addition to pairing responses to requests by parameters it would be also useful to do the pairing according to headers.
Yes yes this would be awesome for me to http://stackoverflow.com/questions/31161915/more-get-request-response-examples-with-different-uri-parameters
@netmilk
how to dereference (exclude,remove) some property
Maybe by considering that Parameters list is not inherited and has to be redefined for each Request...
What do you think?
Hello all, What is the status of this nice feature ? Is it plan to be released soon ?
Thanks, Nestor
