REST API从木愣到够呆

目前准备写一个API服务,遵循REST规范,因为自己也是第一次接触这玩意,所以就以自我的认知和理解过程来记录,留爪.

##在REST里什么叫资源?
拿数据表为例:
现在有三张表:(此表非彼婊)

1. schools #学校表
2. students #学生表
3. teachers #教师表

这些表对应的是一个个数据集,在REST里这些集合个体就叫做资源.

*Tips:*资源对应的是一个集合,那么我们在命名的时候最好用名词+复数形式来表达.

*Tips:*表结构和资源非常像,所以很多人会直接把资源名和表名强制对等(应该视情况而定).

##在REST里什么叫资源操作?
对于表数据的操作不外乎CRUD:

1. C=Create=新建
2. R=Read=读取
3. U=Update=更新/修改/替换
4. D=Delete=删除
   对应的对资源的操作也就是CRUD,

同时HTTP协议本身也有对应的CRUD方法:

1. POST=新建
2. Get=读取
3. Put=更新/修改/替换
4. Delete=删除
   当然,一般我们只用到Get和Post这2种,

而REST是基于HTTP协议的,那么本着有便宜不占白不占的准则,于是在REST里对资源的操作叫做Post/Get/Put/Delete.

##在REST里如何实现对资源的操作?
既然REST是基于HTTP协议来实现来,那么自然而然我们要实现的就是一个HTTP API,也就是实现一个URI,
以操作资源students为例:

• (Get)/students=读取所有学校数据
• (Post)/students=新建学校数据
• (Put)/students=修改学校数据
• (Delete)/students=删除学校数据

那么怎么实现对资源中某项数据的操作呢?

• (Get)/students/:id=读取编号为id的学校数据
• (Post)/students/:id=新建一个编号为id的学校数据
• (Put)/students/:id=修改编号为id的学校数据
• (Delete)/students/:id=删除编号为id的学校数据
  *Tips:*资源对应表结构的话,id其实可以是表的主键.

##在REST里如何确认返回的数据格式及字符集?
HTTP中常见的交互数据格式有json & xml & html & rss等等,常见的编码有utf-8 & gbk等等.

1. 一种做法是在请求参数当中添加format参数来告诉服务端我需要什么格式的数据,如:

• /students?format=xml&charset=utf-8
• /students?format=json&charset=gbk
  
  这样相对肉眼直观,但是会多占用2个参数,并且format参数别名大家并不统一,可能有写人叫format,有些人叫dataType等等,charset类似.

1. 还有一种做法是在HTTP的请求头中来告诉服务端我需要什么格式的数据及字符集,如:

• http.setHeader("Content-Type", "text/html; charset=utf-8")
• http.setHeader("Content-Type", "text/json; charset=utf-8")
• http.setHeader("Content-Type", "text/xml; charset=gbk")
  
  这样相对肉眼隐藏了,减少了明面上的参数,并且HTTP协议是规范固定的,统一性相对较强,但是每次都需要设置请求头,需要一定知识基础.

1. 另外一种做法是URI添加数据格式后缀:

• /students/123.json=读取编号为123的学生数据,并以json数据格式返回
• /students/123.xml=读取编号为123的学生数据,并以xml数据格式返回
  
  而字符集使用通用类型的utf-8则(不管是哪种方式,都推荐字符集用这种)

##在REST里如何解读URI的规则(todo:待补充)?