RESTful API设计总结

随着近年来移动互联网的发展，各种客户端出不穷：Web，IOS，Android。因此需要一种机制使得各种客户端能够和服务端进行通讯，这就使得RESTful API的架构流行起来。另外，搜索公众号互联网架构师后台回复“面试”，获取一份惊喜礼包。RESTful是REST(表现层状态转化)的形容词形式，因此RESTful API就可以理解成“符合REST风格的API”。

格式规范

根据RFC3986定义，URL是大小写敏感的。所以为了避免歧义，尽量使用小写字母。

RESTful API 应具备良好的可读性，当url中某一个片段（segment）由多个单词组成时，建议使用 - 来隔断单词，而不是使用 _。这主要是因为，浏览器中超链接显示的默认效果是文字并附带下划线，如果API以_隔断单词，二者会重叠，影响可读性。

/api/featured-post/     # GOOD
/api/featured_post/     # WRONG

协议

提供给用户的API，总是使用HTTPs协议。使用HTTPs协议还是HTTP协议本身和RESTful API并无关系，但是这对于提高网站的安全性很重要。

域名

API应该放在专有域名下，比如https://api.example.com/v1。也可以简单地把版本放在URL中，比如https://www.example.com/api/v1

版本

API的版本号应该放在URL中：

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

名词应该使用复数

所用的名词往往和数据库的表名对应，而数据库的表是一组记录的集合，因此URL中的名词即表示一组资源的集合，故URI中的名词要使用复数

https://api.example.com/v1/students
https://api.example.com/v1/schools
https://api.example.com/v1/employees

URL中不能使用动词

URI代表着一个资源，是一个实体，应该是名词，而不要把具体的动作放在URL中，对资源的操作应该通过HTTP的动词来实现。

不符合CRUD的情况

如果实在无法表示，也可使用动词，例如search没有对应的HTTP方法，可以在路径中使用search，更加直观

http://api.xxx.com/apiv3/search?timestamp=123213218&user_id=4192121&keyword=2134789。再例如创建了博客网站，如果想要发布一个博客，可以使用POST /articles/{:id}/publish

用HTTP动词表示对资源的操作

使用HTTP协议里的动词来实现资源的获取、删除、添加等操作

GET：从服务器获取资源
POST：在服务器新建一个资源
PUT：在服务器更新资源（客户端提供改变后的完整资源）
PATCH：在服务器更新资源（客户端提供改变的属性）
DELETE：从服务器中删除资源

GET     https://api.example.com/v1/schools                  # 列出所有学校
POST    https://api.example.com/v1/schools                  # 新建一个学校
GET     https://api.example.com/v1/schools/ID               # 列出指定学校的信息
DELETE  https://api.example.com/v1/schools/ID               # 删除指定学校

GET     https://api.example.com/v1/schools/ID/students      # 列出指定学校的所有学生
DELETE  https://api.example.com/v1/schools/ID/students/ID   # 删除指定学校的指定学生

HTTP状态码

200 OK - [GET]：服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
204 NO CONTENT - [DELETE]：用户删除数据成功
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
另外，搜索公众号互联网架构师后台回复“面试”，获取一份惊喜礼包。
401 UNAUTHORIZED：表示用户没有权限（令牌、用户名、密码错误）
404 NOT FOUND：用户发出的请求针对的是不存在的记录，服务器没有进行操作
500 INTERNAL SERVER ERROR：服务器发生错误，用户将无法判断发出的请求是否成功

其它

API的身份认证应该使用OAuth 2.0框架
服务器返回的数据格式，应该尽量使用JSON，避免使用XML。JSON有可读性强，结构紧凑，支持的语言种类多的特点，因此JSON是RESTful API最常用的返回格式。

THE END

PS：如果觉得我的分享不错，欢迎大家随手点赞、转发、在看。

～

RESTful架构和RESTful API设计总结