How can I specify a shared Headers section across all Apiary/Blueprint API requests?

I have a large API document and each request has the same request headers like Accept: application/json and Cookies: SessionID. Is there a way I can declare these globally to avoid the duplication?

Solution

The most common thing I have been applying for that matter is to define a Data Structure, and then use it in all those requests. In my case, I used it for the authorization headers, which are all the same.

Example of a Data Structure and the usage of it (doesn't matter where you actually use it, header or body of the request, in this case is in the body):

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

# Auth API

This is an Auth API, where you can obtain authentication/authorization for your app in our system.

It is necessary that you provide your credentials in order to use the API. The endpoints of the Auth API are only to obtain a valid access token, which would be provided along with each call.

# Group Authentication

## Get a request token [/auth/request]

Obtain a request token so you can exchange it for an access token.

Requests tokens have a short expiry rate, and are only one time use.

### GET

+ Request (application/json)
    + Attributes
        - Authorization (OAuth Request)

+ Response 200 (application/json)

        {
                "oauth_token" : "request-token-ng7805hg85hjt89gu258ty25",
                "oauth_token_secret" : "TOKEN SECRET TO BE USED WHILE SIGNING REQUESTS"
        }

## Exchange a request token for an access token [/auth/exchange]

Once you have got a request token, you will be able to trade it for an access token and then be able to call the different API endpoints.

### GET

+ Request (application/json)
    + Attributes
        - Authorization (OAuth Exchange)

+ Response 200 (application/json)

        {
                "oauth_token" : "AN_INACTIVE_FRESH_ACCESS_TOKEN"
        }

# Data Structures

## OAuth base (object)

+ oauth_consumer_key: YOUR_CONSUMER_KEY (string, required)
+ oauth_nonce: A_UNIQUE_TOKEN_FOR_THIS_REQUEST_GENERATED_BY_YOU (string, required)
+ oauth_signature: A_SIGNATURE_HASH_BASED_ON_THE_REQUEST_PARAMS (string, required)
+ oauth_signature_method: `HMAC-SHA256` (string, required)
+ oauth_timestamp: MILLISECONDS_FROM_EPOC_UNIX_TIME (string, required)
+ oauth_version: 1.0 (string, required)

## OAuth Request (object)

+ Include OAuth base
+ oauth_callback: YOUR_CALLBACK_URL (string, required)

## OAuth Exchange (object)

+ Include OAuth base
+ oauth_token: YOUR_RECENTLY_OBTAINED_REQUEST_TOKEN (string, required)

You only need to add the name of the Data Structure between parentheses, and that's it. You can reuse it as much as you want. Even to build other data structures, in case, as I needed, you want to base other data structures on a previously defined data structure.