RESTful基本要求

RESTful -Representational State Transfer

1 什么是RESTful

• 资源 （Resources）

  网络上的一个实体，或者说是网络上的一个具体信息，并且每个资源都有一个独一无二得URI与之对应；获取资源-直接访问URI即可

• 表现层（Representation）

  如何去表现资源 - 即资源得表现形式；如HTML , xml , JPG , json等

• 状态转化（State Transfer）

  访问一个URI即发生了一次 客户端和服务端的交互；此次交互将会涉及到数据和状态得变化

  客户端需要通过某些方式触发具体的变化 - HTTP method 如 GET， POST，PUT，PATCH，DELETE 等

2 RESTful的特征

• 每一个URI代表一种资源

• 客户端和服务器端之前传递着资源的某种表现

• 客户端通过HTTP的几个动作 对 资源进行操作 - 发生‘状态转化’

3 如何设计符合RESTful 特征的API

• 协议 - http/https

• 域名

  域名中体现出api字样，如

  https://api.example.com

  or

  https://example.org/api/

• 版本:

  https://api.example.com/v1/

• 路径 -

  路径中避免使用动词，资源用名词表示，案例如下

  https://api.example.com/v1/users
  https://api.example.com/v1/animals
  

• HTTP动词语义

  请求动词	说明
  GET（SELECT）	从服务器取出资源（一项或多项）
  POST（CREATE）	在服务器新建一个资源
  PUT（UPDATE）	在服务器更新资源
  DELETE（DELETE）	从服务器删除资源

  具体案例如下：

  请求动作	请求资源	说明
  GET	/zoos	列出所有动物园
  POST	/zoos	新建一个动物园
  GET	/zoos/ID	获取某个指定动物园的信息
  PUT	/zoos/ID	更新某个指定动物园的信息
  DELETE	/zoos/ID	删除某个动物园
  GET	/zoos/ID/animals	列出某个指定动物园的所有动物
  DELETE	/zoos/ID/animals/ID	删除某个指定动物园的指定动物

• 巧用查询字符串

  ?type_id=1：指定筛选条件
  ?limit=10：指定返回记录的数量
  ?offset=10：指定返回记录的开始位置。
  ?page=2&per_page=100：指定第几页，以及每页的记录数。
  

• 状态码

  用HTTP响应码表达 此次请求结果，例如

  响应码	说明
  200 OK - [GET]	服务器成功返回用户请求的数据
  404 NOT FOUND	用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
  500 INTERNAL SERVER ERROR	服务器发生错误