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 回答