Api-blueprint: 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

[aurelienappere]

+1

[aurelienappere]

@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

[ghost]

+1

[sjamog]

+1

[alexzub]

+1

[halysongoncalves]

Hi @zdne ,

Any predictions launch this feature?

[zdne]

Hey @halysongoncalves no progress on this just yet. Fairly high on the wish list but nobody has committed to it just yet. Contribution is welcomed! What is needed – see https://github.com/apiaryio/api-blueprint/issues/58#issuecomment-137787114

[zdne]

Please note we have recently moved to an RFC proposal system (https://github.com/apiaryio/api-blueprint-rfcs). Any substantial change to the syntax should be proposed using the RFC flow and not the PR as I have mentioned in https://github.com/apiaryio/api-blueprint/issues/58#issuecomment-137787114

[zdne]

The RFC for this change can be found at: https://github.com/apiaryio/api-blueprint-rfcs/blob/master/draft/0004-request-parameters.md

[kentcb]

In addition to adding a +1, just wanted to mention my use case for this because I'm not sure the proposed syntax is a great fit...

I am defining paged APIs, so I want to define multiple sample pages of data so that a client built against the mock APIs can be exercised properly. If I understand the proposal correctly, I would need something like this:

### Get the things [GET /things{page}]

+ Parameters
    + page: 1 (number) - page number to retrieve

+ Response 200 (application/json)

    [
        { name: "thing1" },
        { name: "thing2" }
    ]

+ Request First page of results
  + Parameters
    + page: 1

+ Response 200 (application/json)

    [
        { name: "thing1" },
        { name: "thing2" }
    ]

+ Request Second page of results
  + Parameters
    + page: 2

+ Response 200 (application/json)

    [
        { name: "thing3" },
        { name: "thing4" }
    ]

+ Request Third page of results
  + Parameters
    + page: 3

+ Response 200 (application/json)

    [
        { name: "thing5" },
        { name: "thing6" }
    ]

Is my understanding correct? If so, I guess it'll work, but it just seems a little...verbose.

[pksunkara]

@kentcb You have duplicated the first page of results but yes, you are correct in your understanding.

### Get the things [GET /things{page}]

+ Parameters
    + page: 1 (number) - page number to retrieve

+ Response 200 (application/json)

    [
        { name: "thing1" },
        { name: "thing2" }
    ]

+ Request Second page of results
  + Parameters
    + page: 2

+ Response 200 (application/json)

    [
        { name: "thing3" },
        { name: "thing4" }
    ]

+ Request Third page of results
  + Parameters
    + page: 3

+ Response 200 (application/json)

    [
        { name: "thing5" },
        { name: "thing6" }
    ]

It is verbose because you are describing more than one request response pairs. If you use MSON, maybe you can reduce this a bit.

[poku1010]

+1

[jamesdixon]

Can't wait to see this implemented. Our team is working with JSON API, which implements standard paradigms for things like filtering, sorting, specifying returned fields, etc. Without this implemented, it will be difficult to be able to utilize the mock server of Apiary without creating custom resources for each combination of query params needed to manipulate the result set returned.

[zdne]

@jamesdixon The feature is being implemented as we speak. As far as know the core was already implemented. Release is pending.

[johanhar]

Sweet

[johanhar]

@zdne any ETA on when Apiary can use this feature?

[markdrake]

+1

[rrgarciach]

+1

[EdgarArguelles]

+1

[elbelga]

+1

[NagoLazaro]

+1 Would be really helpful to have this feature.

[m-matveev]

+1

[zdne]

Update: This has been partially implemented in the pre-release of the API Blueprint parser.

https://github.com/apiaryio/drafter/releases/tag/v2.3.0-pre.0 (note this is not deployed in Apiary.io)

[MykolaMorozov]

+1

[madhukar93]

+1

[grojguy]

Three cheers and double the beers for whoever releases this. We really need.

[nweber]

Is there any idea when this will be deployed to Apiary.io and when it will be available in Dredd?

[alexeiberkov]

Need it a lot. When it could be deployed ?

[pksunkara]

Hey guys, This feature is only partially implemented. It still doesn't have validation support or documentation support in Apiary. We are working on it but do not have an ETA.

[Ib01]

oh my god this has to be the clunkiest product ever cannot believe i spent 3 hours on it ... pretty micky mouse and they expect how much a month!!! they must be joking

[philipjohn007]

It is weird. This discussion began over 2 years ago and it is not fully implemented yet.

[lmorais]

I need a lot of it

[hueter]

+1

[tommi-lew]

+1

[rajivnyu]

Guys, Any updates on this?

[philsturgeon]

Ha, so many people wanting this, I actually just swung by to check progress myself. Super need. How do I help?

[pksunkara]

Hey guys, With the recent release of drafter 3.0, we have laid down the ground for this feature and will be finishing this up soon. Please understand that this has the highest priority regarding API Blueprint.

[kylef]

And to add to the previous comment, since Drafter 2.3.0. The parser will parse request parameters, the only thing that is missing in the parser is validation of these parameters in some cases. These parameters are respected in the parser output, and therefore is already supported in tools such as Dredd which support it.

Here's a quick example:

HOST: http://httpbin.org

# Parameters in Requests Example
## Response Headers [GET /response-headers{?limit}]

+ Parameters
    + limit: 5 (number)

+ Response 200 (application/json)
    + Attributes
        + limit: 5 (fixed)

+ Request
    + Parameters
        + limit: 10

+ Response 200 (application/json)
    + Attributes
        + limit: 10 (fixed)

$ dredd test.apib http://httpbin.org
info: Beginning Dredd testing...
pass: GET /response-headers?limit=5 duration: 216ms
pass: GET /response-headers?limit=10 duration: 197ms
complete: 2 passing, 0 failing, 0 errors, 0 skipped, 2 total
complete: Tests took 422ms

⚠️ Just want to add caution, that since the validation of these parameters are not yet handled be wary that you can easily use them wrong without notice. ⚠️

RFC4 | Specification PR

[ramede]

+1

[thovt93]

I have the same issue. Have anyone fixed this problem?

[nathanmarcos]

+1

[kentcb]

FWIW, our team has moved away from Apiary. It's been over 2 years since this debilitating issue was opened, and still no fix. :/

[kylef]

@kentcb This has been supported in API Blueprint for a while now, please see my comment a few up: https://github.com/apiaryio/api-blueprint/issues/58#issuecomment-230025964.

[kentcb]

@kylef thanks, but it was still > 2 years after issue opened (we moved off Apiary quite some time ago now). Also, why hasn't this issue been closed then?

[nicolasiensen]

@kylef is Request Parameters going to be available for Swagger? Thanks!

[pksunkara]

Swagger doesn't deal with request response pairing according to the official spec. And we are not in charge of the official spec. So, you will have to ask them directly. If you want to talk about how Swagger Response Params extensions can be supported in Apiary, please do send an email to [email protected]

[m-matveev]

Ned this feature, again (

[elreeda]

+2

[schivmeister]

Hi, I was wondering what the status on this is? @kylef Your example from https://github.com/apiaryio/api-blueprint/issues/58#issuecomment-230025964 first of all throws a warning on Apiary (Invalid header block). After re-arranging the header, the request-response pairs do show up on the Example view. However, going to the Console and testing with the different values via Mock returns the same response (10). I cannot get a response of 5.

I got the impression from the discussion so far that this has already been implemented but not tested and officially documented.

[pksunkara]

@schivmeister It's implemented only on the API Blueprint and not on Apiary side. I was able to get no warnings from the APIB given by Kyle. Which drafter version gave you the invalid header block warning?

[shanvenkat]

Where can I get documentation to convert the API Blueprint specification to .apib file

[xjchengo]

+1
Need this feature on Apiary. Currently there is no error on Apiary editor but Apiary document cannot show different request parameters.

[doozMen]

Wierd that this takes years to release

[GuilleGF]

+1

[balupton]

How long off is a dredd and apiary implementation of this?

I have a use case of a global query param, that adds headers to the response if it exists. I'd like to have the dredd and the API spec provide examples for its existence, and non-existance.

[ferranabello]

+1

[MarianoCornejo]

i was trying to apply the new syntax and then after read all the posts i realize this is not implemented yet, how we are with this? we really need this feature :(

[shimberger]

+1

[zzhjerry]

+1

[lucas-scampos]

+1

[huteri]

After a long discussion for the past 2 years, and it's still not yet implemented? We've seen people who badly need this. Any updates at least?

[upelsin]

+1

[dynjo]

👍

[vs4vijay]

Will this feature work on Swagger format too?

[redsky1991]

+1

[robyedlin]

+1

[ozgur]

When can it be deployed into apiary.io?

[kacper1703]

+1

[noveogroup-amorgunov]

+1