Web API 入门系列 - RESTful API 设计指南
参考：https://developer.github.com/v3/ https://github.com/bolasblack/http-api-guide
HTTP 协议
目前使用HTTP1.1协议，为了通信安全，建议使用https协议
域名
尽量使用专业域名，如 https://api.github.com
也可以使用主域名，如 https://www.github.com/api
API版本
放在请求头里,如Accept: application/vnd.github.v3+json 这种方案URL比较优雅，表示同一资源，github api 推荐这样使用。
URL地址
在RESTful架构中，每个网址代表一种资源，用名称复数形式，不要用动词。
如应该使用： https://api.github.com/books 不应该使用：https://api.github.com/getbooks
过滤分页
分页：?page=2&per_page=100： 如：https://api.github.com/user/repos?page=2&per_page=100 如果没有传递时，使用默认配置。排序：?sortby=name&order=asc： 如：https://api.github.com/user/repos?page=2&per_page=100&sortby=name&order=asc 如果没有传递时，使用默认配置。
过滤：?username=1 如：https://api.github.com/user/repos?username=1
HTTP 动词
Restful 风格的程序推荐使用 http verbs 来操作服务器资源，让资源发生状态转变。
关于方法语义的说明：
GET： 用于从服务器获取某个资源的信息
完成请求后返回状态码 200 OK
完成请求后需要返回被请求的资源详细信息
POST： 用于创建新资源
创建完成后返回状态码 201 Created
完成请求后需要返回被创建的资源详细信息
PUT： 用于完整的替换资源或者创建指定身份的资源，比如创建 id 为 123 的某个资源
如果是创建了资源，则返回 201 Created
如果是替换了资源，则返回 200 OK
完成请求后需要返回被修改的资源详细信息
PATCH： 用于局部更新资源
完成请求后返回状态码 200 OK
完成请求后需要返回被修改的资源详细信息
DELETE： 用于删除某个资源
完成请求后返回状态码 204 No Content
异常处理
在调用接口的过程中，可能出现下列几种错误情况：
服务器维护中，503 状态码
HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Length: 41
{"message": "Service In the maintenance"}
发送了无法转化的请求体，400 状态码
HTTP/1.1 400 Bad Request
Content-Length: 35
{"message": "Problems parsing JSON"}
服务到期（比如付费的增值服务等）， 403 状态码
HTTP/1.1 403 Forbidden
Content-Length: 29
{"message": "Service expired"}
因为某些原因不允许访问（比如被 ban ），403 状态码
HTTP/1.1 403 Forbidden
Content-Length: 29
{"message": "Account blocked"}
权限不够，403 状态码
HTTP/1.1 403 Forbidden
Content-Length: 31
{"message": "Permission denied"}
需要修改的资源不存在， 404 状态码
HTTP/1.1 404 Not Found
Content-Length: 32
{"message": "Resource not found"}
缺少了必要的头信息，428 状态码
HTTP/1.1 428 Precondition Required
Content-Length: 35
{"message": "Header User-Agent is required"}
发送了非法的资源，422 状态码
HTTP/1.1 422 Unprocessable Entity
Content-Length: 149
{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "required"
}
]
}
所有的 error 哈希表都有 resource, field, code 字段，以便于定位错误，code 字段则用于表示错误类型：
missing： This means a resource does not exist.
missing_field： This means a required field on a resource has not been set.
invalid： This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.
already_exists：This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).
身份认证
使用OAuth 2.0验证，参考 http://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html
