如何在所有 Apiary/Blueprint API 请求中指定共享 Headers 部分？

Question

我有一个很大的 API 文档，每个请求都有相同的请求 headers，例如 Accept: application/json 和 Cookies: SessionID。有没有一种方法可以全局声明这些以避免重复？

Answer 1

我申请的最常见的事情是定义一个数据结构，然后在所有这些请求中使用它。在我的例子中，我将它用于授权 headers，它们都是相同的。

数据结构示例及其用法（无论您实际在哪里使用它，请求的 header 或 body，在本例中是在 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)

你只需要在括号之间添加数据结构的名称，就是这样。您可以根据需要重复使用它。甚至构建其他数据结构，以防万一，根据我的需要，您希望其他数据结构基于先前定义的数据结构。

如何在所有 Apiary/Blueprint API 请求中指定共享 Headers 部分？

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

apiary.io

apiblueprint

apiary