Implemented Request Parameters (RFC0004)

[pksunkara]

Things got a little bit more complex because of Resource Model :(

Link to RFC: https://github.com/apiaryio/api-blueprint-rfcs/blob/master/accepted/0004-request-parameters.md

---

This change is 

[zdne]

@pksunkara I would at least expect the link to the RFC in the description. Making it easier for person who reviews it might actually helps to get the review faster. Also this should have do not merge label until it is implemented

[zdne]

@pksunkara please keep in mind providing context and clarity is what we all should aim for, looking at the first 20 lines of diffs I do not recall what RFC0004 was about.

[kylef]

Remember to do the following:

• Update the parent sections for URI Parameters section: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-uriparameters-section

[kylef]

I'd like to see a note mentioning that when you have two URI Parameter sections (request/action and a request level URI Parameter section) one overrides the other and there is no inheritance.

I think this might be ambiguous on how this is handled otherwise.

[pksunkara]

one overrides the other and there is no inheritance.

Why? Requests and responses can't have their own uriTemplate. So, they have to rely on the uriTemplate from the action (or above). So, why can't they inherit the parameters too?

I think they should definitely inherit the action parameters. We are adding the parameters in request to differentiate between different values of parameters which are inherited from the action.

An example would be:

### Search for a question [GET /questions{?query,limit}]

+ Parameters
    + query - Search query
    + limit: 20 (number, optional) - Maximum number of questions returned

+ Response 200 (application/json)

        [
            { "question": "Hello?" },
            { "question": "Favourite programming language?" },
            { "question": "API Description language preference" }
        ]

+ Request A search limited to one result
    + Parameters
        + query: language
        + limit: 1

+ Response 200 (application/json)

        [
            { "question": "Favourite programming language?" }
        ]

Here, query in action parameters is left empty and it's value will be filled by the request parameters.

"Request Parameters" object inherit "Action Parameters" object. No new members will be added since the uriTemplate will be the same. It's just going to be the change of values.

[pksunkara]

I have added an extra line saying the same.

[pksunkara]

@zdne We use "PR: Passed review" label to denote this PR as reviewed and should be merged only after implementation. Not the "PR: Do not merge" label.

[zdne]

@pksunkara why are you mentioning it #293 (comment) ? (besides it should be "Do not merge" + "Passed review" – one is given by the author other by the reviewer)

[pksunkara]

@zdne I was replying to this line from you.

Also this should have do not merge label until it is implemented

I wanted to point out that we do not use "PR: do not merge" labels in this case because we generally use it to denote that a PR is not ready according to the author. Guess, we need more labels 😄

[kylef]

Do we really want to add URI Parameters section to a resource model? Since a resource model doesn't have an associated URI (until it's referenced).

[pksunkara]

I have removed the URI parameters from Resource Model since it is soon to be deprecated anyway. This PR is ready for review now.

[kylef]

I think there should be a comma before unless:

This section should include at least one of the following nested sections, unless specified otherwise by the sections inheriting this section:

[pksunkara]

Addressed.

[kylef]

This looks good to me 👍

[w-vi]

why the URI Parameters are bold?

[pksunkara]

@w-vi Fixed.