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