搜档网

搜档网

当前位置:搜档网 > RESTful API 设计最佳实践 -

RESTful API 设计最佳实践 -

摘要:目前互联网上充斥着大量的关于RESTful API(为了方便,以后API 和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API 格式如何?你的API 是否应该加入版本信息?

背景

目前互联网上充斥着大量的关于RESTful API(为了方便,以后API 和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API 格式如何?你的API 是否应该加入版本信息?当你开始写一个app 的时候,特别是后端模型部分已经写完的时候,你不得不殚精竭虑的设计和实现自己app 的public API部分。因为一旦发布,对外发布的API 将会很难改变。

在给SupportedFu 设计API 的时候,我试图以实用的角度来解决上面提到的问题。我希望可以设计出容易使用,容易部署,并且足够灵活的API ,本文因此而生。

API 设计的基本要求

网上的很多关于API 设计的观点都十分”学院派“,它们也许更有理论基础,但是有时却和现实世界脱轨(因此我是自由派)。所以我这篇文章的目标是从实践的角度出发,给出当前网络应用的API 设计最佳实践(当然,是我认为的最佳了~),如果觉得不合适,我不会遵从标准。当然作为设计的基础,几个必须的原则还是要遵守的:

1.

2.

3.

4.

5. 当标准合理的时候遵守标准。 API 应该对程序员友好,并且在浏览器地址栏容易输入。 API 应该简单,直观,容易使用的同时优雅。 API 应该具有足够的灵活性来支持上层ui 。 API 设计权衡上述几个原则。

需要强调的是:API 的就是程序员的UI ,和其他UI 一样,你必须仔细考虑它的用户体验! 使用RESTful URLs 和action .

虽然前面我说没有一个万能的API 设计标准。但确实有一个被普遍承认和遵守:RESTfu 设计原则。它被Roy Felding提出(在他的”基于网络的软件架构“论文中第五章)。而REST 的核心原则是将你的API 拆分为逻辑上的资源。这些资源通过http 被操作

(GET ,POST,PUT,DELETE)。

那么我应该如何拆分出这些资源呢?

TOP相关主题