Restful API设计 经验总结

标签：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 是最为常用的编码方案。从个人经验而言，除非有特殊要求：

从 API 入口，到业务逻辑处理，再到存储，一律使用 utf-8 编码！

从 API 入口，到业务逻辑处理，再到存储，一律使用 utf-8 编码！

从 API 入口，到业务逻辑处理，再到存储，一律使用 utf-8 编码！

如果要支持 emoji 表情，还需额外的处理。

在 HTTP 协议中，Accept-Charset／Content-Type 头部可以指定字符编码方案。

• Requst 头部: Accept-Charset: utf-8
• Response 头部: Content-Type: charset=utf-8

大部分情况下在请求和返回头部指定序列化协议为json

建议：

采用 JSON 作为序列化和反序列化协议，对于 html 类型应用，使用 XML。

在 HTTP 协议中，Accept／Content-Type 头部可以指定序列化和反序列化协议。

• Requst 头部: Accept: application/json
• Response 头部: Content-Type: application/json

会配置HTTPS证书

机构颁发的证书一般需要万把块钱购买；我们可以使用 openssl 自己制作证书。

推荐阅读

• HTTP Method

https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.7/

• 跟着 Github 学习 Restful HTTP API 设计

http://cizixs.com/2016/12/12/restful-api-design-guide

• Learn REST: A RESTful Tutorial

http://www.restapitutorial.com/

• HTTP 权威指南