Multiple Examples with Different Parameters

[scalabl3]

I am trying to figure out how to do list multiple examples with different parameter combinations and formatting for a single resource/request type that have consistent responses.

## MyAPICall  [/resource/{param1}/{param2}{?jsonp,userID}]

### Example 1 [GET]
+ Parameters
    + param1 (string, `demo`) - Blog Subsection
    + param2 (string, `posts`) - Resources requested, comma separated (%2C encoded comma)
    + jsonp (string, `0`) - jsonp callback identifier, use `0` if not using jsonp
        + userID (string, `1234`) - userID of the caller

### Example 2 [GET]
+ Parameters
    + param1 (string, `demo`) - Blog Subsection
    + param2 (string, `posts%2Ccomments`) - Resources requested, comma separated (%2C encoded comma), i.e. posts,comments is posts%2Ccomments
    + jsonp (string, `0`) - jsonp callback identifier, use `0` if not using jsonp
        + userID (string, `1234`) - userID of the caller

+ Response 200
...

+ Response 404
...

It's also ok if I supply parameter types above the examples, and then just put in examples more simply:

## MyAPICall  [/resource/{param1}/{param2}{?jsonp,userID}]

+ Parameters
    + param1 (string) - Blog Subsection
    + param2 (string) - Resources requested, comma separated (%2C encoded comma)
    + jsonp (string) - jsonp callback identifier, use `0` if not using jsonp
        + userID (string) - userID of the caller

### Example 1 [GET]
+ Parameters
    + param1: `demo`
    + param2: `posts`
    + jsonp: `0`
        + userID: `1234`

### Example 2 [GET]
+ Parameters
    + param1: `demo`
    + param2: `posts%2Ccomments`
    + jsonp: `0`
        + userID: `1234`

+ Response 200
...

+ Response 404
...

Simulated Rendered Example (this is how I wish it looked)

[zdne]

Hey @scalabl3 , I love your way of thinking about this problem! Great stuff!!

Out of curiosity, are familiar with MSON used for attributes description? Have you seen the proposal to use the MSON for parameters and headers description?

I would like to hear your opinion on that if you would find a time...

[zdne]

Also related, the response based parameters are now being implemented. Check https://github.com/apiaryio/api-blueprint/issues/58

(API Blueprint roadmap is here)

[scalabl3]

Yes I saw #58, which is what I was looking at to try to solve this variety of documentation. Multiple Requests/Responses are fine, except that you have to hit "show" to actually see them, but when you do that, you are just showing a code block with headers overridden. It's not easy to read or plainly visible (it feels more hidden).

I like the idea of Request/Response pairs, but multiple example usages in my case are more frequently needed. I only illustrated one above, but I have many cases where there are varieties of parameters and formatting of parameters that end-users need to know and also have an example of, having a simple singular example only covers the simplest of api calls.

Maybe there is a way to have Request/Response grouping be "nested" or "separate" based on the node level of its container?

[zdne]

@scalabl3 I guess there are two things here:

1. Rendering of the #58 in the Apiary documentation
2. Scenario (example) driven documentation

Re 1. It is still open how Apiary docs will render multiple examples based on parameter values

Re 2. API Blueprint is currently reference-like format. We have considered support for scenarios #21 but so far it wasn't a popular request.

[Perni1984]

Re 1. It is still open how Apiary docs will render multiple examples based on parameter values

I like the proposal of @scalabl3 a lot. How can we help to get this implemented?

Re 2. API Blueprint is currently reference-like format. We have considered support for scenarios #21 but so far it wasn't a popular request.

I suppose the proper why to this right now is to come up with an RFC, correct?

[zdne]

I like the proposal of @scalabl3 a lot. How can we help to get this implemented?

I think this is almost implemented in the parser. Maybe @kylef or @pksunkara can point to the exact place where paramers-based response is being implementd

I suppose the proper why to this right now is to come up with an RFC, correct?

Yup. Make sure to check the #21 too

[kylef]

@Perni1984 Yes, there was an accepted RFC 4: Request Parameters which has been implemented.

Support for request parameters has been implemented in the master branch of drafter [via drafter#230]. We are planning to improve the support with additional warnings when the syntax is mis-used.

If you want to use this functionality in your own tools, these parameters will be surfaced via the Refract API Description namespace and can be found under the hrefVariables part of the HTTP Request Message

[kylef]

I forgot to mention, the changes for the API Blueprint specification can be found at https://github.com/apiaryio/api-blueprint/pull/293, merging this is pending a new release of the parser.

[seku]

+1