API设计与开发之最佳实践

Posted 21CTO

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了API设计与开发之最佳实践相关的知识,希望对你有一定的参考价值。

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


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


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


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


什么是参数化?


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


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


—— REST API设计者菲尔丁


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


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


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


问题一:我们要添加什么类型的参数?


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


API设计与开发之最佳实践

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)


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


(未完待续)


相关阅读:






以上是关于API设计与开发之最佳实践的主要内容,如果未能解决你的问题,请参考以下文章

设计 Node.js REST API 的 10 条最佳实践

RESTful API 设计更新 1/多对多关系的最佳实践?

Android最佳实践之高效的应用导航

API设计指南 一个接口文档模板的最佳实践

API设计指南-「干货」一个接口文档模板的最佳实践

Elasticsearch最佳实践之Index与Shard设计