RESTful API

总结翻译自SoloLearn RESTful API 教程

RESTful API

概述

Representational State Transfer 表象状态传输，由美国科学家Roy Thomas Fielding定义，是一种常用在web开发中，用于传递状态信息的一种构建风格和方法。经常用于HTTP web APIs，不需要任何额外的库或者包。
What is HTTP?
HTTP Headers

REST构建约束

提倡使用HTTP原本设想的方法使用HTTP,具体就是GET,POST,PUT,DELETE分别对应查询，创建，修改，删除
REST API层和应用层应该充分解耦，应用层的升级，不会影响API的使用
客户端和服务端之间沟通的的共同的接口，应该标准化，不能被改变
客户端和服务端之间的交换应该是无状态的，每一次请求都要附带所有的认证和授权的信息。为了减少发送重复的信息，REST API鼓励使用缓存机制

Resource Structure

遵循一个共同的命名惯例（Following a consistent naming convention）

资源可以分为两类：Singleton单例和Collection集合
Collection使用复数，Singleton使用id，类似这样：/users/{userID}
资源命名一般使用名词，也可以使用动词表示一个动作，例：/projects/{id}/run
不要使用尾部的/符号，无意义
总是使用-分隔两个单词，_在某些系统字体下可能不显示
总是使用小写
不要使用文件扩展名
总是使用查询字符串（? &），过滤查询结果
不要使用CRUD的函数名，而是默认使用http method的定义

Read Operation(GET)

GET是唯一安全的方法，只是从服务端查询数据，而不做任何修改
GET APIs 具有idempotent幂等性，多次请求会获得相同的结果，直到API（POST或者PUT）修改了服务端资源的状态
状态码：查询到数据返回200（OK），查不到数据返回404（NOT FOUND），请求格式不对返回400（BAD REQUEST）。

Create Operation(POST)

提交数据保存在请求的body里
不具有幂等性，调用两次相同内容的POST方法，会创建两条相同内容的不同资源，id不同
状态码：成功创建数据返回201（Created），并包含一个可以引用到新的资源的实体。很多时候POST不会创建一个可以用URI表示的资源，则返回200（OK）或者204（No Content）

Update Operation(PUT)

当更新的资源不存在时，可以设定是否创建
如果创建成果，返回201，如果成功修改，返回200或者204

Delete Operation(DELETE)

如果删除成功，返回200，并在body中附带删除的item，如果不附带，则返回204（NO CONTENT）

API Version

API升级后可能会存在多个版本，在URL中包含版本信息，来区分处理不同版本的请求，例如：http://api.example.com/v1.1/uers
另一种方法是将版本信息包含在HTTP头部
同时可以为不同的平台设计不同的API,例如Android和IOS使用a-v5和i-v5

Pagination and Partial Response

Partial Response部分响应
请求指定的字段信息，而不是全部，可以使用逗号分隔字段，例如
/users/?fields=name,status,avatar
Pagination分页
使用两个参数来控制分页：offset和limit，例如
/users/?offset=0&limit=20
offset和limit应该都有一个默认值，在缺少的时候被使用。

URI Design for Search

搜索应该指定搜索的范围，表明是全局或局部的搜索，例如：

http://api.example.com/search?q=new+web+codes
http://api.example.com/users?q=pending+lessons

查询字符串中的空格会被转换成+好，而空格在url的其他地方被转义成%20