Response based on parameter values

[martijnschouwe]

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'
• 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!

[zdne]

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?

[martijnschouwe]

@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:

[alyssaq]

+1 I would love this feature

[sergiofbsilva]

need this pretty bad :+1:

[gaffney]

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 :/

[zdne]

@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)?

[gaffney]

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=n format. 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.

[zdne]

@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!

[gaffney]

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.

[margru]

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?

[zdne]

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.

[margru]

Great! I hope it arrives soon :)

[zdne]

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

[richthegeek]

+1 on this, seems like a very obvious missing feature! Let me know what I can do to help get it working.

[zdne]

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

[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.

[pit3k]

+1 Great feature. And we badly need it.

[altsanz]

+1 on this. It would be amazing!

[tuo]

+1. it is huge pain for us, hopefully it could get implemented asap

[tony612]

+1 We need it too!

[ifeins]

+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.

[zdne]

@ifeins fairly high on our list – will start working on it soon™ :dancers:

[marko85to]

+1 Super feature, really needed!! Would be great to have it!

[jirikrepl]

Yes yes this would be awesome for me to http://stackoverflow.com/questions/31161915/more-get-request-response-examples-with-different-uri-parameters

[shavo007]

+1

[ghost]

+1

[ghost]

@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?

[narg95]

Hello all, What is the status of this nice feature ? Is it plan to be released soon ?

Thanks, Nestor

[efavre]

Hi,

Would love to see this too.

[mlovretovich]

+1

[lyttlegy]

+1

[edude03]

:+1: any movement on this?

[zdne]

No updates, besides the fact it is currently at the top of our todo list together with authentication syntax.

[dysbulic]

:+1: I'd love to be able to mock enough responses the teams using the API can work as I implement.

[hendrikmaus]

+1

[ruipinge]

+1

[jcolaco-nmz]

+1

[jdduarte]

+1

[craigryan]

+1

[poshaughnessy]

:+1:

[vatson]

:+1:

[dysbulic]

I put down some money for whoever does this: https://www.bountysource.com/issues/2007613-response-based-on-parameter-values

[SukitZhang]

+1

[nicstrong]

+1

[makowskid]

+1 ???

[zdne]

Big thanks to everyone expressing your support on this issue! I want to ensure you we still have this on the top of our feature list.

I feel a status update is appropriate here: At the moment, we are all working on radically changes in the parser toolchain so everyone can build new tools on the freshly introduced MSON. Once we clean & tighten up our parser toolchain we will get back to introducing new, much needed, features.

Please bear with us! Thank you 👍

PS: Of course any contributions are welcome!

[OrCharles]

@zdne I would like to help. Can you point me to where you're looking for help specifically? Anything troubling?

[zdne]

Hey @OrCharles, thanks for offering hand!

In order to move this forward – 3 things are needed:

1. Verify and formally (Pull request) propose the syntax including examples
2. Make sure API Blueprint AST and API Description Refract namespace can hold the information proposed in 1.
3. Implement parsing in the API Blueprint parser – Snow Crash

I guess we have to start from step 1 – so if you are up for it to formalize the subject including some examples it would be great !

[tomasz-scislo-xstream]

+1

[khaliddermoumi]

+1