RESTful-github.api 介绍

本文结合GitHub API v3介绍RESTful接口的设计规则

1. api与用户通信总是使用HTTPS协议：https://api.github.com；
2. 尽量将API部署在专属域名下，https://api.github.com；加入API很简单，不会有扩展，则可以考虑放到主域名下，例如https://www.github.com/api;
3. 版本号放在url中，https://developer.github.com/v3；或将版本号放在头信息中，例如访问https://api.github.com的REST（V3版本）时，Accept: application/vnd.github.v3+json；
4. api网址，或者说是endpoint，每个endpoint代表一种资源，这也是路径不能为动词的原因：用户https://api.github.com/users；某个用户某个仓库的issue**https://api.github.com/repos/username/repo_name/issues?parameter=val; 某个用户的仓库https://api.github.com/user/repos；
5. 对资源的操作类型，由HTTP verb表示。curl -X DELETE/POST/… api.example.com;[注]curl -H 表示定义请求头；
6. 过滤信息，Filtering information，当请求内容较多时，使用limit、offset（指定开始位置），分页、排序、筛选等方式限制返回信息量：curl 'https://api.github.com/user/repos?page=2&per_page=100'；
7. URL定位资源；http动词表示操作；status code 表示操作结果：2XX成功、3XX重定向、4XX客户端错误、5XX服务器错误；

REST(resource representation status transaction)资源表征状态转移

1. 所有操作都是无状态（Stateless）的：服务端生成响应客户端请求的数据中包含状态转移的数据，客户端借助这份数据可以进行状态转移，例如获取列表的“下一页”<a rel="next" href="/yasserg/crawler4j/issues?page=2&amp;q=is%3Aissue+is%3Aopen">,另一个状态（下一页连接）和状态转移的方向next（表示连接为下一页）都有服务器生成存放在客户端；
2. 带参考博文这里写链接内容