New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Multiple Examples with Different Parameters #310

Open
scalabl3 opened this Issue Feb 4, 2016 · 9 comments

Comments

Projects
None yet
5 participants
@scalabl3

scalabl3 commented Feb 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@zdne

zdne Feb 8, 2016

Contributor

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

Contributor

zdne commented Feb 8, 2016

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

This comment has been minimized.

Show comment
Hide comment
@zdne

zdne Feb 8, 2016

Contributor

Also related, the response based parameters are now being implemented. Check #58

(API Blueprint roadmap is here)

Contributor

zdne commented Feb 8, 2016

Also related, the response based parameters are now being implemented. Check #58

(API Blueprint roadmap is here)

@scalabl3

This comment has been minimized.

Show comment
Hide comment
@scalabl3

scalabl3 Feb 9, 2016

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?

scalabl3 commented Feb 9, 2016

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

This comment has been minimized.

Show comment
Hide comment
@zdne

zdne Feb 19, 2016

Contributor

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

Contributor

zdne commented Feb 19, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@Perni1984

Perni1984 Feb 26, 2016

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?

Perni1984 commented Feb 26, 2016

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

This comment has been minimized.

Show comment
Hide comment
@zdne

zdne Feb 26, 2016

Contributor

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

Contributor

zdne commented Feb 26, 2016

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

This comment has been minimized.

Show comment
Hide comment
@kylef

kylef Feb 26, 2016

Member

@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

Member

kylef commented Feb 26, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@kylef

kylef Feb 26, 2016

Member

I forgot to mention, the changes for the API Blueprint specification can be found at #293, merging this is pending a new release of the parser.

Member

kylef commented Feb 26, 2016

I forgot to mention, the changes for the API Blueprint specification can be found at #293, merging this is pending a new release of the parser.

@netmilk netmilk referenced this issue Mar 1, 2016

Closed

Migration to API Elements #388

11 of 12 tasks complete
@seku

This comment has been minimized.

Show comment
Hide comment
@seku

seku commented Sep 19, 2017

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment