REST API

REST API

译自REST API

认证

通过token进行请求api认证。

获得token后，可以将其作为Bearer token提供给API：

$ curl -H 'Authorization: Bearer token' https://site.enchant.com/api/v1/tickets

注意：token持有者拥有访问你帐户的权限，所以token应当像密码一样受到保护。

请求

基本API的URL为https://site.enchant.com/api/v1，其中site应替换为你域名标识。

HTTPS

所有的请求必须通过HTTPS发送。任何通过原始HTTP发送的请求会失败。

JSON Bodies

所有的请求都为JSON编码并且必须有Content-Type: application/json，否则API将会返回415 Unsupported Media Type状态码。

$ curl https://site.enchant.com/api/v1/users/543abc -X PATCH -H 'Content-Type: application/json' -d '{"first_name":"John"}'

HTTP Verbs

我们通过标准的HTTP请求来表示每个请求的意图：

• GET - 查询一个资源或该类所有资源
• POST - 创建一个资源
• PUT - 整体修改一个资源
• PATCH - 部分修改一个资源
• DELETE - 删除一个资源

Limited HTTP Clients

如果你使用的HTTP客户端不支持PUT、PATCH、DELETE请求，则可以发送带有X-HTTP-Method-Override头部的POST请求：

$ curl https://site.enchant.com/api/v1/users/543abc -X POST -H "X-HTTP-Method-Override: DELETE"

如果您使用的HTTP客户端不支持将“Bearer”方案作为Authorization标头的一部分发送，token可以由Basic Auth提供：

$ curl -u token:X https://site.enchant.com/api/v1/tickets

响应

所有的响应主体都为JSON编码。

单个资源表示为JSON对象：

{
  "field1": "value",
  "field2": true,
  "field3": []
}

资源的集合表示为JSON对象数组：

[
  {
    "field1": "value",
    "field2": true,
    "field3": []
  },
  {
    "field1": "another value",
    "field2": false,
    "field3": []
  }
]

时间戳采用UTC格式，格式为ISO8601。

未设置的字段将被表示为null而不是不存在。如果该字段是数组，则将其表示为空数组-即[]。

HTTP Status Codes

我们使用HTTP状态代码来指示请求成功或失败。

Success codes:

• 200 OK - 请求成功。包括响应
• 201 Created - 资源已创建。
• 204 No Content - 请求成功，但没有响应主体

Error codes:

• 400 Bad Request - 无法解析请求
• 401 Unauthorized - 未提供身份验证凭据或身份验证失败
• 403 Forbidden - 经过身份验证的用户无权访问
• 404 Not Found - 找不到资源
• 415 Unsupported Media Type - 发生POST / PUT / PATCH请求，但没有application/json内容类型
• 422 Unprocessable Entry - 由于验证错误，修改或创建资源的请求失败
• 429 Too Many Requests - 由于速率限制，请求被拒绝
• 500, 501, 502, 503, etc - 发生内部服务器错误

Errors

所有400系列错误（400、401、403等）都将以主体中的JSON对象和application / json内容类型返回。

{
   "message": "Not Found"
}

500系列错误代码（500、501、502等）不返回JSON主体。

Validation Errors

由于POST / PUT / PATCH请求上的验证错误，将返回422 Unprocessable Entry的实体状态代码。JSON响应主体将包含错误消息数组。

{
  "message": "Validation Failed",
  "errors": [
    {
      "message": "Field is not valid"
    },
    {
      "message": "OtherField is already used"
    }
  ]
}

Rate Limiting

对于整个服务来说包括所有endpoints、users、tokens，API限流每分钟100次。一个请求通常算作一次。但是embedding和counting 会增加请求的次数。所有的响应必须包括当前API限流的状态：

Rate-Limit-Limit: 100
Rate-Limit-Remaining: 99
Rate-Limit-Used: 1
Rate-Limit-Reset: 20

• Rate-Limit-Limit - 当前限流的总次数
• Rate-Limit-Remaining - 剩余限流的次数
• Rate-Limit-Used - 当前请求所消耗的次数
• Rate-Limit-Reset - 还剩多少秒重置限流总次数

如果达到限流，再请求的话API会返回429 Too Many Requests状态码。这种情况下，你的应用不应该发送任何请求，直到重置限流，也就是在Rate-Limit-Reset这段时间不应该发送请求。

Field Filtering

API的所有响应都可以将字段限制为仅您需要的字段。只需传入带有逗号分隔的所需字段列表的fields查询参数

例如：

GET /api/v1/users?fields=id,first_name

将会返回以下响应正文：

[
  {
    "id": "543abc",
    "first_name:": "John"
  },
  {
    "id": "543add",
    "first_name:": "Bob"
  }
]

Embedding

许多endpoints支持相关资源的嵌套查询以减少API的来回请求。

Embedding通过传入一个embed请求参数来触发，请求参数值以逗号分隔。

GET /api/v1/tickets/543abc?embed=labels

{
  "id": "543add",
  "type": "email",
  "label_ids": [ "123abc", "234bcd" ],
  "labels": [
    {
      "id": "123abc",
      "name": "Refund"
    },
    {
      "id": "234bcd",
      "name": "VIP"
    }
  ],
  ... other ticket fields ...
}

某些endpoints只能嵌套查询某些资源类型。endpoints文档指出了哪些可以嵌套查询。

每个嵌套类型查询都会使用掉相关的限流次数。

Counting

返回集合的所有endpoints都可以提供结果总数的计数。要请求计数，只需将count=true作为查询参数即可。该计数将在响应头部Total-Count中返回。

GET /api/v1/tickets?count=true

200 OK
Total-Count: 135
Rate-Limit-Limit: 100
Rate-Limit-Remaining: 98
Rate-Limit-Used: 2
Rate-Limit-Reset: 20
Content-Type: application/json

[
  ... results ... 
]

请注意，该计数代表可用结果的总数，而不是作为当前响应的一部分返回的总数。

Counting也会使用掉相关的限流次数。

Enveloping

如果您的HTTP客户端难以读取状态码或标头，我们可以将所有内容整齐地打包到响应主体中。只要包含envelope=true作为请求参数，API就会始终返回200HTTP状态码。真正的状态、标题和响应将在主体中。

GET /api/v1/users/does-not-exist?envelope=true

200 OK

{
  "status": 404,
  "headers": {
    "Rate-Limit-Limit": 100,
    "Rate-Limit-Remaining": 50,
    "Rate-Limit-Used": 0,
    "Rate-Limit-Reset": 25
  },
  "response": {
    "message": "Not Found"
  }
}

Pagination

收集请求可以返回0到100个结果，这些结果由per_page和page查询参数控制。所有endpoints默认限制为10个结果。

GET /api/v1/tickets?per_page=15&page=2

并不是所有endpoints都支持分页，具体详情查看相关API文档。

Sorting

一些endpoints支持结果排序，使用sort请求参数可以触发排序。sort的值是用逗号分隔的字段列表。您可以在字段前添加-降序排序。并非所有字段都可以排序。API文档会列出相关支持排序的字段。

所有endpoints的默认排序是created_at降序。

要获取最近更新的票证，请按以下顺序以updated_at降序排列：

GET /api/v1/tickets?sort=-updated_at