Skip to content

Latest commit

 

History

History
188 lines (122 loc) · 7.22 KB

overview.md

File metadata and controls

188 lines (122 loc) · 7.22 KB

概述

该文档包含了 OpenAPI V2 的基本概念和所需资源的描述。

纲要

所有的 API 都将通过 HTTPS 从 https://openapi.zaoshu.io/v2 请求。往返数据内容均为 JSON 格式。

curl -i https://openapi.zaoshu.io/v2

HTTP/1.1 200 OK
Server: nginx
Date: Sat, 21 Oct 2017 23:59:00 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK

Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate

参数传递

很多的 API 接口接受可选参数的传递。对于 GET 请求，所有未在请求路径中以分段指定的参数，都可以通过 HTTP 请求字符串传递：

curl -i "https://openapi.zaoshu.io/v2/instance/d872c7bbfca643a0834d7d2241f69e2b?status=running"

在该示例中，请求路径中的值 'd872c7bbfca643a0834d7d2241f69e2b' 将作为参数 :id 的传入，而 :status 则通过请求字符串传递。

对于 POST、PATCH、PUT 和 DELETE 请求，在 URL 请求字符串中未被包括的部分将会被编码后以 JSON 的方式传递：

curl -i -u username -d '{"result_notify_uri":["https://your-webhook.com"]}' https://openapi.zaoshu.io/v2/instance/d872c7bbfca643a0834d7d2241f69e2b/run

访问根节点

通过 GET 请求根节点能够得到所有的 API 接口项：

curl https://openapi.zaoshu.io/v2

客户端错误码

HTTP 动词语义

API v2 会尽可能为请求动作分配合适的 HTTP 动词。

动词 描述
GET 用于资源索取
POST 用于资源创建
PATCH 用于通过提供部分数据的 JSON 对资源进行更新。例如，爬虫实例有 title 和 result_notify_uri 两个属性。PATCH 请求可以接受一个或多个属性的参数传入来更新对应的资源。
PUT 用于替换掉对应的资源。
DELETE 用于（软）删除对应的资源

授权校验

你可以在控制面板->设置中获取 API 授权的 key 与 secret。

详情请查看授权校验文档。

分页

返回多个项目的请求将会做分页处理，默认每页 30 个项目，你可以通过指定 ?page 参数来获取更多的分页内容。部分 API 中你可以通过指定 ?per_page 参数来增加单页的项目数量，最大值为 100。需要特别说明的是，由于实现原因，部分接口不支持 ?per_page 参数。

curl 'https://openapi.zaoshu.io/v2/instances?page=2&per_page=100'

注意，分页数从 1 开始计算，没有 ?page 参数时默认返回第一页内容。

频率限制

对于授权成功的请求，你每小时最多可以发起 5000 次。你可以通过任意的 API 请求的返回头部获取到当前的频率限制详情：

curl -i https://openapi.zaoshu.io/v2/user/
HTTP/1.1 200 OK
Date: Mon, 01 Jul 2017 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4500
X-RateLimit-Reset: 137270087

返回头中的以下字段包含了关于频率限制的所有信息：

头名称 描述
X-RateLimit-Limit 使用者每小时被允许的最大请求量
X-RateLimit-Remaining 当前的频率限制窗口时间内剩余可用的请求量
X-RateLimit-Reset 当前频率限制窗口重设的剩余时间，格式为UNIX 时间

一旦使用超过频率限制，你会收到错误返回：

HTTP/1.1 403 Forbidden
Date: Tue, 20 Aug 2017 14:50:41 GMT
Status: 403 Forbidden
X-RateLimit-Limit: 6000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1377013266

{
            "msg": "API rate limit exceeded for xxx.xxx.xxx.xxx."
}