Api-blueprint: Common url parameters for all requests

[bazo]

Hi,

our api requires that client add an apiKey, signature and timestamp as a query string to every request

so i have to repeat this query part in every resource definition like this

## Client [/clients/{id}?apiKey={apiKey}&signature={signature}&timestamp={timestamp}]

and then parameters

+ Parameters
    + apiKey (required, string, `2961654ce6c3d01c79edc98c8d930d4cc663cda4`) 
    + signature (required, string, `213213jjflkjdsfl343k4jjfdsdsf`) 
    + timestamp (required, integer, `1443620910`) 

since we have endpoints operating on collections and then on single resource, i have to copy paste this for every group at least twice and then modify the url templates which take some additional query params

when you have a lot of resource group this gets quite tedious, and if you add another common required query param, you have to update everything

i suggest adding some commonParams section to the top of blueprint document and these parameters would be then applied to all requests

[kylef]

Hi @bazo, while this isn't currently supported. We do have a proposal for this in https://github.com/apiaryio/api-blueprint-rfcs/pull/3 (https://github.com/apiaryio/api-blueprint-rfcs/blob/zdne/mson-parameters/draft/mson-parameters-headers.md#parameters). It's a planned feature.

Where you can reference and inherit from other parameters.

# Resource [/resource/{client}{?signature,apiKey,timestamp}]
+ Parameters (Authentication)
    + client: foo

# Data Structures
## Authentication (Parameters)
+ apiKey: 2961654ce6c3d01c79edc98c8d930d4cc663cda4 
+ signature: 213213jjflkjdsfl343k4jjfdsdsf
+ timestamp: 1443620910 (integer)

[pksunkara]

I think he has a good question in here:

so i have to repeat this query part in every resource definition like this

@zdne What do you think? Can we do something about repeating of the uri template?

[pksunkara]

I am really tempted to reopen this issue. I think this issue is more about defining common parameters for more than 1 resource and less about using MSON style syntax.

@zdne Would really love it if you can provide an opinion on this.

[kylef]

Being able to define these in some kind of custom authentication scheme would be ideal. Similar to https://github.com/apiaryio/api-blueprint-rfcs/blob/kylef/authentication-oauth2/draft/authentication-oauth2.md.

[pksunkara]

That's okay if they are Authentication related parameters. I am talking about other parameters such as page, per_page etc.. Basically anything that can be used for all resources.

[borekb]

Would use this as well.

[varenc]

@kylef the link you referenced in your October 1, 2015 comment no longer works. Advice on convenient ways to specify that every endpoint requires an OAuth 2 bearer token would be appreciated.

[jars]

Any update on this?

Having Parameters act like Attributes in their ability to do simple inheritance from a centralised data-structures.md would make our blueprints code-base much more maintainable/DRY.