REST API最佳实践

ShevaKuilin 发布于2019-08-16 10:48 / 2299人阅读

摘要：最佳实践渐渐成为向外曝露服务的通用方式。有效的使用状态码定义了非常多的状态码，这些码对客户端非常有意义。下面是状态码的列表和摘要表示对应的或操作成功。

REST API最佳实践

REST渐渐成为向外曝露服务的通用方式。之所以这么流行的原因主要是简单，易于使用，使用HTTP协议（REST可以用于所有协议，但应用最广泛的是HTTP）等。但是所有向外暴露的资源都被认为是REST是一种误解，是不正确的。在这里，我会向你介绍一些在你实现自己的REST API时你应该谨记的最佳实践。

扩展阅读：REST vs SOAP

下面是一个导读列表

1.名词，不要用动词

2.使用复数

3.文档

4.接口版本

5.分页

6.使用SSL

7.HTTP方法

8.有效的使用HTTP状态码

1.名词，不要动词

REST API开发人员的一个不好的习惯是使用动词来命名REST接口。你应该使用名词来替代动词。

场景

要新建一个REST web services用来获取印度的农民数据。同时，该接口也可以获取其他的信息比如收入，农作物名称，地址等和农民相关的数据。每一个农民都指派了unique ID。
同样的，服务也需要提供农民关联的农作物的信息的接口。

最佳实践

为所有的操作提供单一的endpoint.在下面的例子中，我们为所有的操作（get,add,update,delete）提供了一个endpoint "/farmers",通过不同的HTTP method 来调用不同的操作，下面还会详细介绍。

/farmers

/crops

尽量避免

尽量避免在命名中使用动词。推荐在数据中或者HTTP method提现操作。不要像下面这样命名REST

/getFarmers

/updateFarmers

/deleteFarmers

2.使用复数

使用复数来命名REST服务。这是在REST设计者讨论中的热门话题。

最佳实践

/farmers

/farmers/{farmer_id}

尽量避免

/farmer

/farmer/{farmer_id}

注意

在实践中不要混用单数或者复数命名，虽然我说使用复数是最佳实践，但是如果你坚持使用单数，那么就在所有的服务上执行相同的策略。

3.文档

对软件实现文档化是非常好的习惯，对REST API也是同样。如果你写下了有用的文档，这将使其他开发者收益。对于REST API的常见注释，主要是列出API的endpoints，对每一个endpoint描述其支持的功能列表。有很多工具可以自动完成这件事情。这些工具有：DRF DOCs,Swagger,Apiary

4.接口版本

任何软件都会进化，对于API的每一个比较大的变动，可能需要不同的版本号。如果对API版本化，是REST开发者社区的热门话题。一般来说，有两种方法来将接口版本化

URI 版本化

使用URI的简单例子是

http://host/v2/farmers

http://host/v1/farmers
主要的缺点有

破坏了存在的URI，所有的客户端需要跟着改

增加了需要管理的URI，这会导致增加客户端保存多个URI版本的缓存增加。会降低缓存的命中率，也会降低应用的运行效率。

非常不具弹性，不能简单的修改单个资源或者资源的子集。

媒体类型版本化

这个方法是通过在request的header上增加接口的版本信息。当我们改变URI的资源类型和语言时，我们要修改request的头信息。这个方法对于REST API的版本化是最好的选择。
媒体类型不再是application/json,而是像下面这样：
GET /account/5555 HTTP/1.1
Accept: application/vnd.farmers.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.farmers.v1+json
通过这个方法，客户端可以选择要请求的版本。虽说这个方法比URI版本化来得好，但是通过header传输的不同版本的请求缓存的复杂度也大大上升了。简单的说，当客户端基于URI做缓存，这是简单的，但是通过媒体类型来缓存就增加了复杂性。

5.分页

通过HTTP发送大量数据是一个糟糕的做法。这会引发性能问题，因为序列化大的json对象非常耗时耗资源。建议将结果分页并提供前后的导航链接。
如果你在应用中使用分页，一个较好的做法是使用Link HTTP header option. 这篇文章 link from GitHub应该有用。会帮你打开思路。

6.使用SSL

使用SSL是必须的。REST API必须得到SSL的保护。引用在因特网上发布，无法保证安全的接入。随着越来越多的计算机犯罪事件，我们必须以正确的方式来保护我们的应用。
API的安全已经有成熟的工业标准。不要使用简单的认证机制。可以使用Oauth1.0a或者Oauth2来使接口变得安全。建议使用最新的Oauth2。

7.HTTP方法

当你知道各个HTTP方法所扮演的角色后，将操作映射到HTTP的方法是非常简单的。在前面提及要使用HTTP方法来表示资源的操作，而不是通过不同的服务名字。本节会大致介绍各个HTTP方法的行为模式。
下面两点是在使用HTTP方法前需要考虑的两个方面：

安全：当调用方法时不会改变资源的状态，就认为该HTTP方法时安全的。比如，当通过GET方法获取数据，因为不会修改数据，所以这个方法就是安全的。

幂等：调用资源多次，所获得的回应是相同的，这就是幂等。比如，当你尝试更新数据，每次的返回都相同。
不是所有的方法都是安全和幂等的。下面是一个可以用在REST API调用的列表，表示各个方法安全和幂等的情况

GET          安全        幂等
POST         不安全      不幂等
PUT          不安全      幂等
DELETE       不安全      幂等
OPTIONS      安全        幂等
HEAD         安全        幂等

下面是各个方法的简要说明，在使用的时候请参考：

GET:这个方法是安全且幂等的。常用于获取数据。

POST:这个方法不安全也不幂等。常用于创建资源。

PUT:这个方法是幂等。常用于更新资源。需要避免使用POST来更新资源。

DELETE:常用语删除资源，但是这个方法并不是对所有的请求幂等的。

OPTIONS:这个方法不是用来操作资源的。当客户端不清楚对应的资源有哪些操作时，使用该操作获得资源的表示。

HEAD:可以用来查询一个资源。和GET非常想，但是就如在HTTP的规定所解释的，HEAD方法必须在header中发送请求和获得回应。

8.有效的使用HTTP状态码

HTTP定义了非常多的状态码，这些码对客户端非常有意义。你的REST API可以有效的使用这些状态码来帮助客户端。下面是状态码的列表和摘要：

200 OK - 表示对应的GET,PUT,PATCH 或 DELETE操作成功。也可以用于POST表示没有创建成功。

201 Created - 表示POST创建成功

204 No Content - 表示一个成功的响应，body为空（比如 delete）

304 Not Modified - HTTP缓存

400 Bad Request - 表示request错误，比如body解析出错

401 Unauthorized - 提供了错误的认证信息。可以在这个错误之后触发认证功能。

403 Forbidden - 当认证成功，但是对应的用户没有对应资源的权限时。

404 Not Found - 表示请求一个并不存在的资源

405 Method Not Allowed - 一个认证的用户，调用了他所不允许使用的方法时。

410 Gone - 表示资源已经不可用。比如调用了一个老的API版本。

415 Unsupported Media Type - request提供了错误的content type

422 Unprocessable Entity - 验证错误

429 Too Many Requests - 因为负载限制，拒绝request时。

GPU云服务器云服务器 api设计的最佳实践最佳实践 webrtc最佳实践 cdn最佳实践

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/70479.html

编写 Node.js Rest API 的 10 个最佳实践

摘要：要对进行黑盒测试测试的最好办法是对他们进行黑盒测试，黑盒测试是一种不关心应用内部结构和工作原理的测试方法，测试时系统任何部分都不应该被。此外，有了黑盒测试并不意味着不需要单元测试，针对的单元测试还是需要编写的。本文首发于之乎专栏前端周刊，全文共 6953 字，读完需 8 分钟，速度需 2 分钟。翻译自：RingStack 的文章 https://blog.risingstack.co...

ermaoL 2019-08-20 14:43 评论0 收藏0
PHP / Laravel API 开发推荐阅读清单

showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社区优秀文章 Laravel 5.5+passport 放弃 dingo 开发 API 实战，让 API 开发更省心 - 自造车轮。 API 文档神器 Swagger 介绍及在 PHP 项目中使用 - API 文档撰写方案推荐 Laravel API 项目必须使用的 8 个...

shmily 2019-06-28 18:34 评论0 收藏0
现代后端开发者必备技能-2018版

摘要：现在开始创建一个包并分发给其他人使用，并确保遵循你迄今为止学到的标准和最佳实践。第步实践对于练习，继续编写单元测试，以完成目前为止所做的实际任务，特别是你在步骤中所做的练习。今天的Web开发与几年前完全不同，有很多不同的东西可以很容易地阻止任何人进入Web开发。这是我们决定制作这些循序渐进的视觉指南的原因之一，这些指南展示了更大的图景，并让任何人清楚了解他们在网页开发中扮演的角色。 ...

eternalshallow 2019-07-01 12:27 评论0 收藏0
2018最新后端开发人员的路线图

摘要：简评之前，后端开发路线图仅仅是一个技术推荐，且没有明确的方向指明应该遵循的顺序，这份重新制作的指南将会给你一个更好的方向。现在开始创建一个包并分发给其他人使用，并确保遵循迄今为止学到的标准和最佳实践。简评：之前，后端开发路线图仅仅是一个技术推荐，且没有明确的方向指明应该遵循的顺序，这份重新制作的指南将会给你一个更好的方向。现在的 Web 开发与几年前完全不同了，有很多不同的东西可以...

王陆宽 2019-08-16 12:33 评论0 收藏0
专治前端焦虑的学习方案

摘要：不过今天我希望能够更进一步，不仅仅再抱怨现状，而是从我个人的角度来给出一个逐步深入学习生态圈的方案。最后，我还是想提到下对于的好的学习方法就是回顾参照各种各样的代码库，学习人家的用法与实践。本文翻译自A-Study-Plan-To-Cure-JavaScript-Fatigue。笔者看到里面的几张配图着实漂亮，顺手翻译了一波。本文从属于笔者的Web Frontend Introduc...

codeGoogle 2019-08-21 14:41 评论0 收藏0