RESTful API设计

1.总使用HTTPS协议

2.域名

子域名：api.wython.com    (存在跨域问题)
url:   www.wython.com/api/

3.版本

www.wython.com/api/v1
www.wython.com/api/v2

4.路径,视网络上的任何东西为资源，均使用名词表示(也可是复数)

www.wython.com/api/v1/order
www.wython.com/api/v1/animals

5.请求方式methon不同

GET：从服务器取资源
POST： 在服务器新建资源
PUT： 更新资源(全部更新,例用户表更新用户名,密码,有邮箱)
PATCH: 更新资源(局部更新,只更新用户名或密码)
DELETE： 删除资源

6.过滤，通过url上传参的形式传递搜索条件

www.wython.com/api/v1/order?page=1  指定返回第几页以及每页的记录

7.状态码

2xx 操作成功
3xx 重定向
    301 永久重定向
    302 临时重定向
4xx 客户端访问错误
    400 请求资源不存在，输错地址之类的
    401 用户没有得到访问权限
    403 Forbidden 表示用户得到授权但访问被禁止
5xx 服务端错误

8.错误处理，返回错误信息error方做key

9.返回结果，针对不同操作，服务器向用户返回的结果应符合一下规范

GET/collction: 返回资源对象的列表
GET/collction/resource: 返回单个资源对象
POST/collction: 返回新生成的资源对象
PUT/collction/resource: 返回完整的资源对象
PATCH/collction/resource: 返回完整的资源对象
DELETE/collction/resource：返回一个空文档

10.Hypermedia API,返回结果中提供链接，连向其他API方法，使得用户不查看文档也知道下一步应该做什么

摘自：http://www.ruanyifeng.com/blog/2014/05/restful_api.html

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。
{"link": {
  "rel":   "collection https://www.example.com/zoos",
  "href":  "https://api.example.com/zoos",
  "title": "List of zoos",
  "type":  "application/vnd.yourformat+json"
}}
上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。
{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  // ...
}
从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到了下面结果。
{
  "message": "Requires authentication",
  "documentation_url": "https://developer.github.com/v3"
}
上面代码表示，服务器给出了提示信息，以及文档的网址。