Different actions in the same resource should allow different parameters

[ecordell]

Consider the example from the Gist API:

## Gists Collection [/gists{?since}]
Collection of all Gists.

### List All Gists [GET]
+ Parameters
    + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.

+ Response 200

### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 

+ Request (application/json)

+ Response 201 (application/hal+json)

Since the POST description is under the collection /gists{?since}, it implies that there is a parameter for the post request that doesn't actually exist. This is parsed weirdly on apiary:

, and throws warnings for undefined parameters when using protagonist.

I think a simple solution would be to simply allow overriding the URI further down the tree. Something like this:

## Gists Collection [/gists]
Collection of all Gists.

### List All Gists [GET /gists{?since}]
+ Parameters
    + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.

+ Response 200

### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 

+ Request (application/json)

+ Response 201 (application/hal+json)

[zdne]

@ecordell

Interesting. From my point of view it was just the way how Apiary renders it. You can already have a discussion of an URI (query) parameter on both resource and action level. This is also properly reflected in the parsed AST.

So what a tool, such as Apiary, could already do is to display the information about the parameters only at the appropriate level.

In the case of our Gists collection example it should be rendered in the documentation only for the List All Gists action.

Also could you please be specific on what you mean by "and throws warnings for undefined parameters when using protagonist"?

Now with all that it still might be good to have an explicit support for this in the format and your proposal might be the way to go.

What I would love to see, however, is to come up with a format where you do not have to essentially declare a parameter in an URI Template and then later pick up on the declaration and define the rest. In other words I would love to completely skip the declarative part of it and build URI (or at least query) parameters by just specifying them in the Parameters section of respective resource or action.

Thoughts?

[ecordell]

From my point of view it was just the way how Apiary renders it.

In that case, should I open an issue on uservoice to address this?

Also could you please be specific on what you mean by "and throws warnings for undefined parameters when using protagonist"?

Right, this is why I made the issue instead of assuming it was just an issue with Apiary. When I run tests with Dredd, I get these errors during the "runtime compilation" step.

Runtime compilation warning:
Ambigous URI template: /gists{?since}
Parameter not defined:'since'

This is from compiling the Gist Fox example above. I don't see these warnings when passing the blueprint to the snowcrash cli directly. So actually, this is just an issue with Dredd. It does some checks in expand-uri-template-with-parameters.coffee that doesn't seem to account for the situation I'm describing. (see here).

Once again it seems I've made an issue on the wrong project!

What I would love to see, however, is to come up with a format where you do not have to essentially declare a parameter in an URI Template and then later pick up on the declaration and define the rest.

Is there something that stops that being done right now? It seems like the format could easily support that:

## Gists Collection [/gists]
Collection of all Gists.

### List All Gists [GET]
+ Parameters
    + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.

+ Response 200

### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 

+ Request (application/json)

+ Response 201 (application/hal+json)

It seems like that contains all the information needed to infer the parameters; so it should know that the two URIs are:

• GET /gists{?since}
• POST /gists

More complex examples seem like they would work as well:

## Object Collection [/things/{thingId}/objects]

+ Parameters
    + thingId (string, `ddff123`) ... The id of the thing.

### Filter Objects [GET]

+ Parameters
    + page = `1` (optional, number, `1`) ... The page to retrieve
    + perPage = `10` (optional, number, `30`) ... The number of items per page.
    + q (optional, string, `Potato`) ... A query string.

### Create an Object [POST]

which would generate:

• GET /things/{thingId}/objects{?page,perPage,q}
• POST /things/{thingId}/objects

Or am I missing something?

I think that's a much better solution. It also stops you from documenting the parameters in different orders in different places.

[zdne]

@ecordell

In that case, should I open an issue on uservoice to address this?

You can open it at http://support.apiary.io if you want to track it. However I will personally make sure this will get addressed in the new rendered documentation.

Once again it seems I've made an issue on the wrong project!

Yep the message looks like it comes from Dredd (cc: @netmilk). Many little projects. No worries.

---

Is there something that stops that being done right now?

Well you are pretty much right. The only thing that annoys me is there is still the need for an URI Templates (RFC 6570) in the case of /things/{thingId}/objects.

So it would probably work for query parameters already. And maybe this is enough? But not sure how to do it completely without URI templates.

One can surely nest consecutive parameters /resource/{param1}/{param2} like so:

+ Parameters
    + param1
        + param2

But for the more complex examples e.g. /things/{thingId}/objects/{objectId} it do not see this approach as feasible.

[zdne]

@ecordell

I have just verified that new documentation rendered at Apiary from the following blueprint

# Different Parameters API

## /message{?a,b}

### POST
+ Response 201

### GET

+ Parameters 
    + a (optional, string, `hello`) ... Lorem Ipsum
    + b (optional, array, `['CA', 'NY']`) ... Lorem Ipsum 2


+ Response 200 (text/plain)

        Hello World!

will display parameters and its description only on the GET action.

The logic is as follows (Cuke):

Background: 
    Given a resource `R` with URI template parameter `X`
    Given a resource `R` action `GET`
    Given a resource `R` action `POST`

Scenario: Resource URI parameter desribed in resource

    When I describe parameter `X` in the resource `R` section
    I should see the parameter and description under action `GET` of resource `R`
    And I should see the parameter and description under action `POST` of resource `R`

Scenario: Resource URI parameter desribed in one of resource actions

    When I describe parameter `X` in the action `GET` section  of resource `R`
    I should see the parameter and description under action `GET` of resource `R`
    And I should NOT see the parameter and description under action `POST` of resource `R`

    When I describe parameter `X` in the action `POST` section of resource `R`
    I should see the parameter and description under action `POST` of resource `R`
    And I should NOT see the parameter and description under action `GET` of resource `R`

Scenario: Resource URI parameter not described at all

    When I do NOT describe parameter `X` in ANY section of resource `R`
    I should see the parameter and description under action `POST` of resource `R`
    And I should see the parameter and description under action `GET` of resource `R`

Please review this behavior and if OK close this issue (as not related to API Blueprint format but rather to its tooling).

[ecordell]

It looks like it doesn't display the parameter descriptions, but it does still display the parameters in the uri template:

So it looks like those are options for a POST uri, when they're not...on the other hand, one could argue that this means that the POST uri is different and therefore needs a different URI Template without the query params at the end (which is what I'm currently doing).

Also this needs to be updated in Dredd too, which will complain that the params don't have example values in the POST request.

[zdne]

@ecordell

Sorry my bad I did make this clear: I was talking about upcoming (and long overdue) rendered documentation revamp (@Baggz is working on). The actual documentation won't be update and should be fully replaced by the new one soon.

Also this needs to be updated in Dredd too...

Oh you are definitely right! I plan to elaborate on #21 API Blueprint Testing on Monday;

Will post there our (in coop \w @netmilk) plans for complete API Blueprint testability including the preliminary scenarios support. But thinking about this maybe Snow Crash should capture this somehow and not leave it "out of band"...

[ecordell]

Ah, okay, gotcha.

I'm interested in the testing plans. I had set aside some time today to write some basic before/after hooks for dredd tests, I might hold off on that to see what you guys have been thinking about.

[zdne]

@ecordell

Have to run now but regarding scenarios it is just a mere sketch. At the moment we are concerned mainly about blueprint testability in the sense of well defined transactions. Scenarios were discussed only marginally.

Will post more on it (and #8) on Monday.

Cheers.

[zdne]

@ecordell

Posted.

OK to close this issues (as this will be addressed in the Apiary product)?

Or do you think API Blueprint and/or the Snow Crash should capture the logic somehow?

[jmrboosties]

What's the status on this? Seems like it's been a while since the devs green-lit the concept, but attempting to implement it in API Blueprint doesn't seem to work. Is there an ETA on release?

[Almad]

@jmrboosties Revamp on the product is rolling out (you can switch it on in Apiary's settings) and should be ready soon.

...if you are asking about the original issue and not about #21 . Any particular example of your use-case? ;)

[jmrboosties]

Hey @Almad, thanks for the help earlier on SO. The use-case I'm describing is one where we have a user resource which you can create, update, or get. They all share a resource model (the responses for each are the same) so they should all be declared under the same ##User [URI template] header.

While you can simply place the update/create parameters inside their respective sections, the editor will throw a warning if it is not laid out in the URI, even if it is a PUT or POST request. Maybe I'm doing something wrong, but it doesn't really make sense to me to include parameters you'd find in the body of the request entity in the URI.

Ideally, the GET request would have a URI like base/users/uid, and the PUT and POST requests would look like base/users/ with their respective parameters listed below in the params table.

Does that make sense? Let me know if anything is worth making a different issue about, I'm happy to help give feedback.

[Almad]

Hi, glad to help.

Can you please post here a snippet of how you think things should look like? I think I have an idea, but just to be sure.

I do believe this will be case for #47 , but let's see.

[jmrboosties]

Here is an example of what I was doing. As you can see in the GET request, for organization i was breaking the parameters into 3 groups (this is based on the issue we discussed earlier on SO). As you know our usage is kind of complicated for the GET, but that's not really the issue here so let's just assume its a normal GET request.

So in the GET, the parameters you would see in the actual URI (/user/uid?param1=true&param2=value) as the path next to the grey GET box.

For PUT however, you'd just want the main part of the URI, since there are no params following a ? symbol. Next to PUT should just be /user/uid, followed by all the expected params in the put body below (I threw in location in there as an example).

Ideally this wouldn't throw any errors or warnings, right now including location (which will never be part of the path or a GET parameter) gives a "There is a semantic issue at line X" warning in the editor.

Does this clarify? Thanks for helping.

[janmoravec]

@jmrboosties Let me just jump in. Please try switching on New Documentation (Settings > Beta Area > New Documentation).—More details are in our blog post.

[zdne]

@jmrboosties @ecordell

This issue has already been addressed in Apiary. The logic conforms to the cuke from my previous comment. As there are no actions needed on the API Blueprint side I am closing this issue. Feel free to continue in this discussion here should you have a question.

Please see this example: http://docs.queryparameters.apiary.io which is extended version of current Apiary default blueprint:

## Notes Collection [/notes{?page,per_page}]
### List all Notes [GET]
+ Parameters
    + page ... page index
    + per_page ... number of notes per page

+ Response 200 (application/json)

        [{
          "id": 1, "title": "Jogging in park"
        }, {
          "id": 2, "title": "Pick-up posters from post-office"
        }]

### Create a Note [POST]
+ Request (application/json)

        { "title": "Buy cheese and bread for breakfast." }

+ Response 201 (application/json)

        { "id": 3, "title": "Buy cheese and bread for breakfast." }

As you can see page and per_page query parameters are discussed only in the List al Notes action and therefore Apiary displays them only for this action.

And not of the Create a Note action

[jmrboosties]

Hm yea, looks like it works in the Documentation section of the site, but not the preview section.

Also, the editor still throws a warning when you declare a parameter not explicitly mentioned in the URI template. This isn't a huge deal, but it'd be nice if it were fixed in a future version. Thanks!

[zdne]

@jmrboosties

Also, the editor still throws a warning when you declare a parameter not explicitly mentioned in the URI template.

Can you please elaborate on this? Why would you document an URI parameter that is not in the URI?

[jmrboosties]

Not a URI parameter, a parameter for the POST/PUT body. For instance,

This is a put request for updating a user. The URI is showing all of the GET parameters, rather than what an actual PUT request would look like (in this example, https://bandsintownfan.apiary-mock.com/users/user_id).

Here is the blueprint code:

## User [/users/{user_id}?{auth}&{mobile, template}]
A single User object

+ Model (application/json)

    An example of the user object

    + Body

            {
                data {
                    test: true
                }
            }

+ Parameters
    + user\_id (required, string, `1048384`) ... an identifying id for the user, it could be a Facebook uid, email address, or device\_auth\_id.
    + auth (required, string, `49849fj332\_93`) ... auth for the provided `user_id`. Facebook users need an access token, email or device users need device_id
    + mobile (optional, boolean) ... `true/false` for whether or not this request is coming from a mobile device.
    + template (optional, string) ... defined template for controlling fields in the response

### Get a User [GET]

+ Request

        Link: https://app.bandsintown.com/users/4848832?access_token=TOKEN&mobile=true&template=TEMPLATE

+ Response 200 (application/json)

        [User][]

### Update a User [PUT]

+ Parameters
    + location (required, string, `San Diego, CA`) ... `location` of the user

+ Request (application/json)

        Link: https://app.bandsintown.com/users/47562663

        { "location": "San Diego, CA" }

+ Response 200 (application/json)

        [User][]

In this example, all I want the PUT request to do is be able to change the user's location. I declared that parameter in the PUT section of the user resource, but not in the URI, because location will never be part of the URI.

Does that make sense? Basically parameters inside the POST/PUT bodies of a request should be able to be declared as a required or optional parameter without having to be part of the URI. Also, in POST/PUT requests it would be nice if the URI didn't include GET style parameters.

Someone suggested earlier being able to declare URIs per request type, so instead of having the URI next to the user resource, you could place it next to the [GET] [POST] requests and so on. This would allow your GET requests to contain all the parameters it would require, and just have the necessary path for others.

[zdne]

A parameter needs to be present in URI template in order to be discussed later. Further more I believe your template is not written correctly and it should be (with or without location) formed like this:

## User [/users/{user_id}{?auth,mobile,template,location}]

Now question is which (query) parameter belongs to what action. Let's break it down:

1. user_id always present because it defines the resource in the question.

   Hence we will discuss the user_id on the resource level:

   ## User [/users/{user_id}{?auth,mobile,template,location}]
   
   + Parameters
       + user_id ... lorem ipsum
   
   

2. auth should be also always present because it bears the auth token needed to access the resource.

   Therefore we will also discuss auth on the resource level:

   ## User [/users/{user_id}{?auth,mobile,template,location}]
   
   + Parameters
       + user_id ... lorem ipsum
       + auth ... lorem ipsum
   
   

3. mobile and template are only relevant to retrieve action (GET).

   Thus we will discuss it only under the GET action:

   ## User [/users/{user_id}{?auth,mobile,template,location}]
   
   + Parameters
       + user_id ... lorem ipsum
       + auth ... lorem ipsum
   
   ### Retrieve [GET]
   
   + Parameters
       + mobile ... lorem ipsum
       + template ... lorem ipsum
   

4. location is specific only to the upsert operation (PUT).

   Hence we will discuss it only under the PUT action:

   ## User [/users/{user_id}{?auth,mobile,template,location}]
   
   + Parameters
       + user_id ... lorem ipsum
       + auth ... lorem ipsum
   
   ### Retrieve [GET]
   
   + Parameters
       + mobile ... lorem ipsum
       + template ... lorem ipsum
   
   
   ...
   
   ### Upsert [PUT]
   
   + Parameters
       + location ... lorem ipsum
   
   ...
   
   

   Does this make sense?

   Basically the rule of thumb is: You enumerate every possible query parameter in the resource URI template and you discuss it either on the resource level when it is used by every action on the resource or only on the specific action(s) level.

   Note there is currently a bug in Apiary which does not render this correctly in more complex situations (like this one demonstrated). We are aware of it and will fix it as soon as possible.

---

/cc @Baggz @abtris

[zdne]

(rant on RFC6570): I find the URI template RFC very complex and thus error-prone; if anyone have a better idea I am willing to hear it!

[davidbarton]

@zdne I don't like the way of declaring all query parameters for the resource and then only using some of them, like you posted above:

## Notes Collection [/notes{?page,per_page}]
### List all Notes [GET]
+ Parameters
    + page ... page index
    + per_page ... number of notes per page

+ Response 200 (application/json)

        [{
          "id": 1, "title": "Jogging in park"
        }, {
          "id": 2, "title": "Pick-up posters from post-office"
        }]

### Create a Note [POST]
+ Request (application/json)

        { "title": "Buy cheese and bread for breakfast." }

+ Response 201 (application/json)

        { "id": 3, "title": "Buy cheese and bread for breakfast." }

How about just to declare uri and then re-declare query parameters for each action like this (or some similar syntax):

## Notes Collection [/notes]
### List all Notes [GET][{?page,per_page}]
+ Parameters
    + page ... page index
    + per_page ... number of notes per page

+ Response 200 (application/json)

        [{
          "id": 1, "title": "Jogging in park"
        }, {
          "id": 2, "title": "Pick-up posters from post-office"
        }]

### Create a Note [POST]
+ Request (application/json)

        { "title": "Buy cheese and bread for breakfast." }

+ Response 201 (application/json)

        { "id": 3, "title": "Buy cheese and bread for breakfast." }

[zdne]

@davidbarton

Well I would rather draft away from RFC6570 more or less. Adding parts of this RFC here and there would IMO make the blueprint confusing even for those who understands it.

What we could do is to omit query parameters completely from URI template and assume that when a parameter that is not in the template is discussed then it is a query parameter specific to the point of discussion.

Picking on @jmrboosties example:

## User [/users/{user_id}]

+ Parameters
    + user_id ... lorem ipsum
    + auth ... lorem ipsum

### Retrieve [GET]

+ Parameters
    + mobile ... lorem ipsum
    + template ... lorem ipsum

...

### Upsert [PUT]

+ Parameters
    + location ... lorem ipsum

...

However I am not sure if this would add clarity or not. Thoughts?

[davidbarton]

@zdne Definitely not.

Maybe by making all sections separate.

+ Url parameters
    ...
+ GET Query parameters
    ...
+ Body parameters
    ...
+ Headers
    ...

Also can I track this bug somewhere?

Note there is currently a bug in Apiary which does not render this correctly in more complex situations (like this one demonstrated). We are aware of it and will fix it as soon as possible.

[zdne]

@davidbarton

Also can I track this bug somewhere?

Good question! Currently we do not have anything else but the "ideas" board

[jmrboosties]

Sorry, I'm in California so I'm always missing out on these conversations while they're happening.

I understand that the current system has you declare all parameters in the URI, and then explain them under the request type (GET, POST, etc) where they will be used.

The issue I'm raising is this: going back to our user example I posted earlier, the "correct" way of doing it is this:

## User [/users/{user_id}?{auth, mobile, template, location}]

Even though location will only be used in the PUT, you declare it as part of the URI. That alone is fine I guess, but the problem arises when you view the documentation and it looks like this:

Even though auth, mobile and template are the only parameters you will use in a GET, location shows up there as well. It'd be nice for location NOT to appear there, since it will never be used in a GET request. In this example, having 1 extra unused parameter is something which can be overlooked, but at least for my case, the final implementation of the Users resource's PUT request has dozens of parameters which it can take, which would result in a really cluttered GET URL template.

Also, in the PUT request, all of the parameters are included in the sample URL template, even though you won't be using any after a ? at all:

What I would like to see here is for the PUT URL template to just have:

http://BASEURL.com/users/user_id

If that goes against what you guys are hoping to achieve with the project I understand, just trying to clarify exactly what my suggestions are. Thanks for being responsive on this issue.

[zdne]

@jmrboosties

Sorry, I'm in California so I'm always missing out on these conversations while they're happening

No worries; we all scattered around the world so whenever you can chime in its fine.

What I would like to see here is for the PUT URL template to just have:
http://BASEURL.com/users/user_id

I believe you mean:

http://BASEURL.com/users/user_id?location

Correct?

Other than that what you suggest is the plan. As per my previous comment this is already possible in a simple example like the one from that comment.

More complex situations (like the one from your example) will be supported.

Also note that the spaces between variables are superfluous as per RFC6570 (again I do not like it on this one) thus:

## User [/users/{user_id}?{auth, mobile, template, location}]

Should really be:

## User [/users/{user_id}{?auth,mobile,template,location}]

Update: The question mark ? must be inside the curly braces...

[jmrboosties]

Yes, sorry about that issue with the ?. We were playing around with something and that was just a leftover typo from that.

What I would like to see here is for the PUT URL template to just have:
http://BASEURL.com/users/user_id
I believe you mean:

http://BASEURL.com/users/user_id?location
Correct?

For this part, I actually do mean just the following:

http://BASEURL.com/users/user_id

In this basic example, location is a parameter, but it is a PUT parameter and is going to be included as part of the request body (in a JSON object) rather than in the URI itself.

So even though location is a PUT-specific parameter, it still shouldn't show up in the URI for the PUT, because the actual link you are using is just the path.

Also, I tried moving some parameter declarations around in the editor to mimic what you were doing in the comment you referenced. When I move parameters from the resource section (##) to the request section (###), they still all appear in all of the URIs for both GET and PUT.

I'll provide the code and screens below:

## User [/users/{user_id}{?auth,mobile,template,location}]
A single User object

+ Parameters
    + user\_id (required, string, `1048384`) ... an identifying id for the user, it could be a Facebook uid, email address, or device\_auth\_id.
    + auth (required, string, `49849fj332\_93`) ... auth for the provided `user_id`. Facebook users need an access token, email or device users need device_id

+ Model (application/json)

    An example of the user object

    + Body

            {
                data {
                    test: true
                }
            }

### Get a User [GET]

+ Parameters
    + mobile (optional, boolean) ... `true/false` for whether or not this request is coming from a mobile device.
    + template (optional, string) ... defined template for controlling fields in the response

+ Request

        Link: https://app.bandsintown.com/users/4848832?access_token=TOKEN&mobile=true&template=TEMPLATE

+ Response 200 (application/json)

        [User][]

### Update a User [PUT]

+ Parameters
    + location (required, string, `San Diego, CA`) ... `location` of the user

+ Request (application/json)

        Link: https://app.bandsintown.com/users/47562663

        { "location": "San Diego, CA" }

+ Response 200 (application/json)

        [User][]

Here is what I get in the GET section of the documentation:

My screen isn't big enough to show all the rows in the Parameters section, but I can just tell you that it accurately includes just user_id, auth, mobile, and template. However, in the URI section up top, location is included as well, even though it is only declared under PUT. From the example you gave in your earlier comment, I'd expect not to see location here.

Any thoughts?

[zdne]

@jmrboosties

In this basic example, location is a parameter, but it is a PUT parameter and is going to be included as part of the request body (in a JSON object) rather than in the URI itself.

So even though location is a PUT-specific parameter, it still shouldn't show up in the URI for the PUT, because the actual link you are using is just the path

Ah understand now. I can see where is the confusion here - the Parameters section is a discussion of URI parameters only. For discussing "body parameters" – fields of a payload that is sent in a request (or received in a response) you best to use a payload discussion. For example, as mentioned here http://stackoverflow.com/a/22777226/634940

I am actually working on a dedicated syntax for discussing payload fields as part of this milestone here: #25

---

As for your other remark (on problems when shuffling parameters around) – this is a bug in Apiary and should be fixed there.

[worldspawn]

Its October now and this still doesn't seem to work (in the beta doc feature).

If i specify
## Stories Collection [/stories/{id}/{?channelId,storyStatus,skip}]

On any actions specified I include a parameters section the entire set of parameters is included in the resource uri. So if i just have:

### Get a Story [GET]
+ Parameters
    + id (required, uuid) ... The id of the story being requested

The uri of the action is shown as GET /api/stories/id/?channelId,storyStatus,skip when I would have hoped that channelId, storyStatus and skip would not appear in the uri.

Interestingly for my POST which specifies no parameters the url is printed as POST /api/stories

This would be my biggest (only?) gripe with this tool. It basically means the docs output are just wrong

[Baggz]

@worldspawn

Sorry for the troubles! I'm working on it as we speak; we should be able to deploy a fix by the end of this week this week (Sunday, 19 Oct 2014). I'll let you know and will update the issue accordingly.

[worldspawn]

Cheers mate, appreciate it

[Baggz]

@worldspawn

The fix has been deployed. Could you please give it a try and let me know if everything works as expected? Thanks a lot!

[esbanarango]

@Baggz Hello and thank you!

I'm having the same issue, not sure if it's because I have a free account right now and maybe that fix didn't get there.

[janmoravec]

@esbanarango Hello, we'll be sunsetting this version of documentation, the new one (http://blog.apiary.io/2014/03/21/Re-API-Design-for-Humans/) already solves this issue. The way how to switch the new version on is at the end of the blog post.