RESTful API的开发和使用，无非是客户端向服务器发请求（request），以及服务器对客户端请求的响应（response）。具有统一接口的特点，即，使用不同的http方法表达不同的行为：

  • GET（SELECT）：从服务器取出资源（一项或多项）
  • POST（CREATE）：在服务器新建一个资源
  • PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）
  • PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）
  • DELETE（DELETE）：从服务器删除资源
  • GET /tickets # 获取ticket列表
  • GET /tickets/12 # 查看某个具体的ticket
  • POST /tickets # 新建一个ticket
  • PUT /tickets/12 # 更新ticket 12.
  • DELETE /tickets/12 #删除ticekt 12

常用的Response要包含的数据和状态码（status code），不完善的内容，欢迎大家补充:

  • 当GET, PUT和PATCH请求成功时，要返回对应的数据，及状态码200，即SUCCESS
  • 当POST创建数据成功时，要返回创建的数据，及状态码201，即CREATED
  • 当DELETE删除数据成功时，不返回数据，状态码要返回204，即NO CONTENT
  • 当GET 不到数据时，状态码要返回404，即NOT FOUND
  • 任何时候，如果请求有问题，如校验请求数据时发现错误，要返回状态码 400，即BAD REQUEST
  • 当API 请求需要用户认证时，如果request中的认证信息不正确，要返回状态码 401，即NOT AUTHORIZED
  • 当API 请求需要验证用户权限时，如果当前用户无相应权限，要返回状态码 403，即FORBIDDEN

 最后，关于Request 和 Response，不要忽略了http header中的Content-Type。以json为例，如果API要求客户端发送request时要传入json数据，则服务器端仅做好json数据的获取和解析即可，但如果服务端支持多种类型数据的传入，如同时支持json和form-data，则要根据客户端发送请求时header中的Content-Type，对不同类型是数据分别实现获取和解析；如果API响应客户端请求后，需要返回json数据，需要在header中添加Content-Type=application/json。

使用方式

GET http://www.birjemin.com/api/user # 获取列表

POST http://www.birjemin.com/api/user # 创建用户

PUT http://www.birjemin.com/api/user/{id} # 修改用户信息

DELETE http://www.birjemin.com/api/user/{id} # 删除用户信息

设计要素

  • 资源路径： /users , /articles
  • HTTP动词： GET,POST,DELETE,PUT
  • 过滤信息： 文章分页筛选
  • 状态码： 200，404，422，403…
  • 错误处理：输出JSON格式错误信息
  • 返回结果：输出JSON数组或JSON对象
  • version，必须向前兼容，版本号可放入head（有时把版本号放在URL里要比放在请求的首部中更容易实现和使用）

 

速度限制
如果对访问的次数不加控制，很可能会造成 API 被滥用，甚至被 DDos 攻击。根据使用者不同的身份对其进行限流，可以防止这些情况，减少服务器的压力。为此 RFC 6585 引入了HTTP状态码429（too many requests）。加入速度设置之后，应该提示用户，至于如何提示标准上没有说明，不过流行的方法是使用HTTP的返回头。

对用户的请求限流之后，要有方法告诉用户它的请求使用情况，Github API 使用的三个相关的头部：

X-RateLimit-Limit: 用户每个小时允许发送请求的最大值
X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目
X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成X-RateLimit-Limit的值
如果允许没有登录的用户使用 API（可以让用户试用），可以把 X-RateLimit-Limit 的值设置得很小，比如 Github 使用的 60。没有登录的用户是按照请求的 IP 来确定的，而登录的用户按照认证后的信息来确定身份。

对于超过流量的请求，可以返回429 Too many requests状态码，并附带错误信息。而 Github API 返回的是403 Forbidden，虽然没有 429 更准确，也是可以理解的。

宗旨：


漂亮、简洁、优雅