背景
本文写作时间：2017 年 3 月 30 日；
GitHub 版本：V3；
一直在用前后端分离的方式开发，接口的规范一直在努力使用 REST API 规范，但遇到稍微复杂一点的接口就不知道怎么定义了，例如分页、要查询的字段、筛选条件和排序条件等。
目标
- 根据 GitHub 接口系统学习 REST API 规范；
- 解决当前遇到的问题；
- 要查询的字段、筛选、排序条件；
- 分页；
- PATCH 和 PUT 的具体区别；
- 创建成功和失败时的响应内容；
- 登录和鉴权；
GitHub 接口
因为 GitHub 接口功能非常丰富，为了重点学习自己需要的，按照对于当前的重要程度来区别不同的接口功能。
概要
协议：HTTPS
根端点（Root Endpoint）：https://api.github.com
格式：默认 JSON
字段：见如下示例，如果不存在用 null 而不是忽略掉
示例：
curl -i https://api.github.com/users/octocat/orgs
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-GitHub-Media-Type: github.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff
支持的 HTTP 动词：
- HEAD
- GET
- POST
- PATCH
- PUT
- DELETE
重要
认证
三种认证方式
基础认证
curl -u "username" https://api.github.com
OAuth2 认证（头部发送）
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
OAuth2 认证（作为参数发送）
curl https://api.github.com/?access_token=OAUTH-TOKEN
登录失败
无效的认证信息回返回 401 错误：
curl -i https://api.github.com -u foo:bar
HTTP/1.1 401 Unauthorized
{
"message": "Bad credentials",
"documentation_url": "https://developer.github.com/v3"
}
在短期内一直错误的话，会返回 403 错误：
curl -i https://api.github.com -u valid_username:valid_password
HTTP/1.1 403 Forbidden
{
"message": "Maximum number of login attempts exceeded. Please try again later.",
"documentation_url": "https://developer.github.com/v3"
}
分页
API 自动对请求的元素分页，不同的 API 有不同的默认值，可以指定查询的最大长度，但对某些资源不起作用。
请求
- 通过
per_page设置每页的元素数量； - 通过
page设置要查询的页码； - 如果两项都不设置，系统根据默认的
per_page和page值返回；
响应
测试的 API 端点：https://api.github.com/search/code?q=addClass+user:mozilla&page=14
响应如下：
HTTP/1.1 200 OK
Server: GitHub.com
Date: Thu, 30 Mar 2017 05:47:30 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 161418
Status: 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1490852910
Cache-Control: no-cache
X-GitHub-Media-Type: github.v3; format=json
Link: <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=15>; rel="next", <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=34>; rel="last", <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=1>; rel="first", <https://api.github.com/search/code?q=addClass+user%3Amozilla&page=13>; rel="prev"
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Allow-Origin: *
Content-Security-Policy: default-src 'none'
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
Vary: Accept-Encoding
X-Served-By: 7b641bda7ec2ca7cd9df72d2578baf75
X-GitHub-Request-Id: CB87:1B3BB:E967A5:128F029:58DC9BF1
{
"total_count": 2525,
"incomplete_results": false,
"items": [
...
]
}
响应头 Link 里面包含了相关页面的链接。响应体里面 total_count 表示总数量，items 是数组，里面是要查询的元素。
客户端错误
无效 JSON 会导致 400 错误
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message":"Problems parsing JSON"}
错误的 JSON 格式会导致 400 错误
HTTP/1.1 400 Bad Request
Content-Length: 40
{"message":"Body should be a JSON object"}
无效的字段会导致 422 错误
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field" // missing, missing_field, invalid, already_exists
}
]
}
参考资料
一般
不重要
获取 API 支持的端点
目标：查询 API 支持的端点；
curl https://api.github.com
API 版本号
目标：允许客户调用指定版本的接口
Accept: application/vnd.github.v3+json
媒体类型
目标：可以根据 Accept 请求头返回对应的媒体类型；
HTTP 跳转
目标：合适的时候会使用 HTTP 跳转，状态码是 301/302/307；
条件查询
大部分响应回返回一个 ETag 头。很多响应也会返回一个 Last-Modified 头。你可以使用这些头的值来对那些资源使用 If-None-Match 和 If-Modified-Since 做子查询。如果资源没有修改，返回 304。
