8

我正在为响应中包含的字段不同的 API 编写规范。我希望能够提供多个示例来说明这一点。我的用例是:

  1. 其中一个 API 调用有一个include参数,允许用户指定一些附加字段以包含在响应中
  2. 对于某些 API 调用,响应中包含的字段取决于与用户的 API 密钥关联的权限

我想做的是这样的:

+ Response 200 (application/json)

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com"
    }

+ Response 200 (application/json)

  If `include=telephone` was specified:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com",
      "telephone": "0123456789"
    }

+ Response 200 (application/json)

  If the API key has access to address data:

    {
      "id": 1, 
      "name": "Joe Bloggs",
      "email": "joe@example.com",
      "address": [{
          "address1": "101 My street",
          "address2": "My area"
      }]
    }

据我所知,尽管您可以提供多个响应,但只有在响应代码或内容类型不同时才能这样做。有没有办法做到这一点?

4

1 回答 1

6

更新:这已经实现,请参阅API 蓝图规范


原答案:

TL;DR:不支持,计划中

据我所知,尽管您可以提供多个响应,但只有在响应代码或内容类型不同时才能这样做。

你的发现确实是正确的。目前没有办法做到这一点。最近一直在思考这个想法。解决方案似乎是解除这个限制实现隐式事务示例——自动请求响应配对

请注意,在您的情况下,这在我看来就像基于请求的两个不同的交易示例

(伪代码):

Example 1: 
- Request With Phone Number
- Response With Phone Number 200 (application/json)

Example 2: 
- Request Default
- Response Default 200 (application/json)

假设include=telephone是一个 URI 查询参数,这个计划的功能将需要在自动配对旁边还有描述 URI 参数值的语法。

于 2014-02-25T20:19:36.487 回答