跟着 Github 学习 Restful HTTP API 设计

清华大佬耗费三个月吐血整理的几百G的资源，免费分享！....>>>

　　近几年提供 HTTP API 服务的公司越来越多，许多公司都把 API 作为产品重要的一部分，作为服务提供出去。而微服务的兴起，也让企业内部开始重视和频繁使用 HTTP API 。好的 HTTP API 设计容易理解、符合 RFC 标准、提供使用者便利的功能，其中经常被拿来作为教科书典范的当属 Github API。这篇文章就通过 Github API 总结了一些非常好的设计原则，可以作为以后要编写 HTTP API 的参考。

　　注意：这篇文章只讨论设计原则，不是强制要求（API 设计者可以根据实际情况实现部分内容，甚至实现出和某些原则相反的内容），也不会给出实现的思路和细节。

　1. 使用 HTTPS

　　这个和 Restful API 本身没有很大的关系，但是对于增加网站的安全是非常重要的。特别如果你提供的是公开 API，用户的信息泄露或者被攻击会严重影响网站的信誉。

　　NOTE：不要让非SSL的url访问重定向到SSL的url。

　2. API 地址和版本

　　在 url 中指定 API 的版本是个很好地做法。如果 API 变化比较大，可以把 API 设计为子域名，比如 https://api.github.com/v3；也可以简单地把版本放在路径中，比如 https://example.com/api/v1。

　3. schema

　　对于响应返回的格式，JSON 因为它的可读性、紧凑性以及多种语言支持等优点，成为了 HTTP API 最常用的返回格式。因此，最好采用 JSON 作为返回内容的格式。如果用户需要其他格式，比如 xml，应该在请求头部 Accept 中指定。对于不支持的格式，服务端需要赶回正确的 status code，并给出详细的说明。

　4. 以资源为中心的 URL 设计

　　资源是 Restful API 的核心元素，所有的操作都是针对特定资源进行的。而资源就是 URL（Uniform Resoure Locator）表示的，所以简洁、清晰、结构化的 URL 设计是至关重要的。Github 可以说是这方面的典范，下面我们就拿 repository 来说明。

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch