Restful API

什么是REST

REST，即Representational State Transfer的缩写,中文翻译为"表现层状态转化"，通俗的理解为“URL定位资源，用HTTP动词（GET，POST，DELETE，PUSH等）描述操作”。
REST指的是一组架构约束条件和原则。

什么是Restful APT

如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。
Restful API就是由后台(SERVER端)来提供接口，前端来调用。前端调用API向后台发起HTTP请求，后台响应请求将处理结果反馈给前端。

RESTful API的特征

• 基于“Resource”，数据也好、服务也好，在Restful设计里一切都是资源。

• 统一接口。Restful风格的数据元操作CRUD(create,read,update,delete)分别对应HTTP方法：GET用来获取资源，POST用来新建资源(也可以用于更新资源)，PUT用来更新资源，DELETE用来删除资源，这样就统一了数据操作的接口。
  常用的HTTP方法有下面五个（括号里是对应的SQL命令）。

  • GET（SELECT）：从服务器取出资源（一项或多项）。
  • POST（CREATE）：在服务器新建一个资源。
  • PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  • DELETE（DELETE）：从服务器删除资源。
    还有两个不常用的HTTP动词。
  • HEAD：获取资源的元数据。
  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

• HTTP状态码，在REST中都有特定的意义：200，201，202，204，400，401，403，500。比如401表示用户身份认证失败，403表示你验证身份通过了，但这个资源你不能操作。

• 无状态。一次调用一般就会返回结果，不存在类似于“打开连接-访问数据-关闭连接”这种依赖于上一次调用的情况。

• 将API的版本号放入URL；URL中通常不出现动词，只有名词且URL语义清晰、明确。
  例如：/api/v1/posts/

  URI设计上的一些技巧使用：

  • _或者-来让URI可读性更好使用；
  • ／来表示资源的层级关系；
  • 使用？来过滤资源；如：
    ?limit=10：指定返回记录的数量。
    ?current_page=2&showCount=10：指定第几页，以及每页的记录数。
    ?search_type=1：指定筛选条件。
  • ，或者；可以表示同级资源的关系。

• 使用JSON不使用XML。
  例如：

{ 
   "msg":"uri_not_found", 
   "code":10001, 
   "request":"GET/v2/goods/1227"
   }

当发送非法JSON会返回 400 Bad Request

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Problems parsing JSON"}

参考资料：

• 什么是RESTful API
• REST与RESTFul API最佳实践
• RESTful 架构详情
• RESTful API编写指南