Restful API设计经验总结

陈黎栋

发布于 2020-02-18 15:06:34

5260

发布于 2020-02-18 15:06:34

文章被收录于专栏：陈黎栋的专栏啦陈黎栋的专栏啦

标签：MVC、计算机网络

最近协助项目组，设计了一些Restful API，把设计的经验在这里总结一下。

如何设计 Restful API

URI 设计

作为 Restful 的核心特性，uniform interface 是面向资源的，我们用 URI 来指代某个资源。比如，我们用如下 URI 代表账号系统用户 john：

http://example.com/users/john

为了简便，后续例子可能会省略域名，用 /users/john 表达相同含义。

查询用户 john 的请求如下。

GET /users/john

更新用户 john 的请求如下。

PUT /users/john

删除用户 john 的请求如下。

DELETE /users/john

从上可以看出，不论是查询还是删除用户 john，我们都用相同的 URI 来表指代这个用户(资源)，采用不同的 Http Method 来表示不同的操作类型。既然 /users/john 指代的是用户 john，顾名思义，/users 指代的是所有的用户，所以可以用如下请求查询所有的用户信息。

GET /users

因为 URI 代表的是某个资源，而资源本身是个名词，所以在设计 URI 时，也应该用名词，切记不要使用动词等词语。比如，如下 URI 是面向动作的，不满足 Restful 风格约束。

/users/getuser

帐户系统在不同阶段可能会有不同的版本，比如 v1，v2，我们通常把版本号放在前面，比如：

/v1/users/john /v2/users/john

如果需要查询某些符合要求的资源，可在 URI 的 paras 模块设置查询参数，如查询所有性别为女的用户

GET /users?gender=female

如果返回结果过多，可以加上分页功能，如查询自 john 起的 10 位用户。

GET /users?limit=10&marker=john

此外，在设计 uri 时，还应该注意如下要点：

尽量用小写：比如用 john，最好不要用 John。
用中杠 -，不用下杠 _

充分利用已有Response Code的含义

设计 API 时，请先深入理解 HTTP Response Code，充分利用它们代表的含义，除非特别需要，尽量不要去自己定义额外的返回码，以免引起误解。让我们一起回顾下常见 HTTP Response Code 的含义。

见另一篇笔记。

在请求和返回头部指定编码为最通用编码utf-8

ASCII 编码计算机最早采用的字符编码，随着计算机在多个国家普及，几乎每个语言都有一套或者多套自己的编码，如汉字的 GBK 编码，日语的 Shift_JIS 编码。这些编码方案各不相同，非常容易造成兼容性问题。Unicode 的诞生很好的解决了上述问题，它使计算机能够跨语言、跨平台进行文本转换和处理。Unicode 字符集包含了世界上所有文字和符号，它有 utf-8，utf-16 等编码方案，其中 utf-8 是最为常用的编码方案。从个人经验而言，除非有特殊要求：