背景

本文写作时间：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。

参考资料

• 媒体类型

参考资料

• GitHub API