API设计与开发之最佳实践

Posted 2021-05-01 21CTO

导读：本文来详解REST API设计中参数和查询字符串使用的最佳实践。

在设计API时，我们的目标是为用户提供动力，而不是我们提供的服务。虽然HTTP的谓词和资源允许程序员使用一些交互，如果添加更多功能，则系统会变得繁琐，难以使用。

举一个常见的分页例子：如果数据库有数百万条记录，我们不可能在一个响应中将每篇文章都发送给客户端。

达成这项目作的方法就是使用查询字符串，即参数化。

什么是参数化？

通常来说，参数化就是一种请求配置。在编程语言中，可以让函数返回值，如果函数不使用任何参数，则不会影响该返回值，API也是如此，尤其是像REST API这样的无状态接口。

“任何REST交互都是无状态的。即每个请求都包含查询请求所需要的全部信息，而与之前的任何请求无关”。

—— REST API设计者菲尔丁

HTTP中有许多方法可以向请求添加参数：查询字符串、POST正文、PUT和PATCH请求以及HTTP标头，这些也都有自己的用例和规约。

把参数都放在数据中的最简单方法就是使用POST。很多API都以这种方式工作着，每个节点都使用POST，将参数写在HTTP内容中。十年前这种API积累的特别多，那么这些接口就不适合查询字符串。

当然，现在的情况不都是这样，这是API设计中一个边缘案例。如果在设计之前能够预先提出正确的问题，可以避免一些错误的结果。

问题一：我们要添加什么类型的参数？

我们应该问自己的第一个问题：要添加什么类型的参数？它应该是一个在HTTP RFC文档中定义好的规范：

RFC文档：http://www.rfcreader.com/#rfc2616_line4589

这上面定义了很多标准字段。有时候，我们可以重新发明轮子，并将信息添加到另一个地方。不是说我们不能用不同的方法来做事。比如，GraphQL从REST的角度做了人们认为比较疯狂的事情，但它秦效了。

但是，使用已经成熟的技术会更简单。

我们以HTTP标头为例，它能够让我们定义格式或媒体响应类型。我们也可以用它来告诉API需要何种格式，也可以用它来获取API的版本，如JSON还是XML。

还有一个重要的HTTP标头，API开发者可以用它来防止浏览器缓存，不必有随机的查询字符串避免被缓存。

如Cache-Controlno-cache (?q=<RANDOM_STRING>)

API授权也可以被视作一个参数。API提供授权的详细信息，授权或未经授权的响应也会有所不同。

HTTP RFC定义了授权（Authorization）标头：

关于授权的说明（http://www.rfcreader.com/#rfc2616_line4922）

当检查好全部默认字段后，下一步是评估为参数创建自定义字段，还是把它放在查询字符串中。

（未完待续）

相关阅读：