RESTful 理解

什么是RESTful

RESTful是一种设计原则。只要我们的服务满足这种设计原则，那我们的服务便可以称之为RESTful服务。

以资源为中心

RESTful api 强调资源，api的设计应该使用名词性描述而非动词，每一个uri代表一个资源，用户通过不同的动作（GET, PUT, POST, DELETE）对资源进行操作。一般来说，GET用于获取资源，POST用于新建资源，PUT用于更新资源的所有属性（所以一般我们直接使用POST），DELETE用于删除资源。

  # RESTful api
  # 获取学号为id学生的信息　
  GET api/students/id  　
  
  # 新建一个学生资源　
  POST api/students
  args id = XX name = XX .. 　　
  　　
  #　更新一个学生资源
  POST api/students/id
  args name=XX ..
    
  #　删除一个学生资源
  DELETE api/students/id

返回合适的状态码

在HTTP Response中，响应码是一个很重要的字段，它反应了请求的状态。一个设计良好的api应该设计明确的status code以及错误提醒信息。　　
一般来说，status code分为2XX，3XX，4XX，5XX这几种类型，2XX 表示请求成功，服务器完成处理；3XX表示资源重定向，请求的资源位置发生了变化；4XX 发送的请求错误；5XX 服务器端错误。下面是常见的status code:

200 　OK 　请求成功接收并处理，一般响应中都会有 body

201 　Created 　　请求已完成，并导致了一个或者多个资源被创建，最常用在 POST 创建资源的时候

202 　 Accepted 　请求已经接收并开始处理，但是处理还没有完成。一般用在异步处理的情况，响应 body 中应该告诉客户端去哪里查看任务的状态

204 　No Content 　请求已经处理完成，但是没有信息要返回，经常用在 PUT 更新资源的时候（客户端提供资源的所有属性，因此不需要服务端返回）。如果有重要的metadata，可以放到头部返回

301 　Moved Permanently 　请求的资源已经永久性地移动到另外一个地方，后续所有的请求都应该直接访问新地址。服务端会把新地址写在 Location 头部字段，方便客户端使用。允许客户端把 POST请求修改为 GET。

304 　 Not Modified 　请求的资源和之前的版本一样，没有发生改变。用来缓存资源，和条件性请求（conditional request）一起出现

307 Temporary Redirect 目标资源暂时性地移动到新的地址，客户端需要去新地址进行操作，但是不能修改请求的方法。

308 Permanent Redirect 和 301 类似，除了客户端不能修改原请求的方法

400 　 Bad Request 客户端发送的请求有错误（请求语法错误，body 数据格式有误，body 缺少必须的字段等），导致服务端无法处理

401 　 Unauthorized 请求的资源需要认证，客户端没有提供认证信息或者认证信息不正确

403 　Forbidden 服务器端接收到并理解客户端的请求，但是客户端的权限不足。比如，普通用户想操作只有管理员才有权限的资源。
404 　Not Found 客户端要访问的资源不存在，链接失效或者客户端伪造 URL 的时候回遇到这个情况

405 　Method Not Allowed 服务端接收到了请求，而且要访问的资源也存在，但是不支持对应的方法。服务端必须返回 Allow 头部，告诉客户端哪些方法是允许的

415 　Unsupported Media Type 服务端不支持客户端请求的资源格式，一般是因为客户端在 Content-Type 或者 Content-Encoding 中申明了希望的返回格式，但是服务端没有实现。比如，客户端希望收到 xml返回，但是服务端支持 Json

429 　Too Many Requests 客户端在规定的时间里发送了太多请求，在进行限流的时候会用到

500 　Internal Server Error 服务器内部错误，导致无法完成请求的内容

503 　Service Unavailable 服务器因为负载过高或者维护，暂时无法提供服务。服务器端应该返回 Retry-After 头部，告诉客户端过一段时间再来重试

Hypermedia API

Hypermedia：在返回结果中提供相关资源的链接。举个不是很恰当的例子，还是以学生为例：

GET api/students/id
# response
{
   student_id: XX,
   student_class: "api/classses/id",
   chinese_score: "api/students/id/chinese",
   ...
}

类似这种，用户可以根据返回的结果继续后面的操作

编写文档

对每个请求以及返回的参数进行描述，如果可以给出详细而完整的示例。

文章参考：

理解RESTful架构
跟着 Github 学习 Restful HTTP API 设计
What Is REST?