RESTful API设计系列一:简介

说明

简介

这篇文章里,我尝试写下我心中的、真正优美的RESTful API设计原则。这些经验来自于我之前参与的项目twice,它是红帽企业版中的虚拟化产品。在API设计阶段我们必须解决真实场景中的很多问题,同时我们不希望添加那些容易实现的非RESTful或者类RPC接口到我们的API中。

在我的理解中,真实的RESTful API提供了问题的答案,你不需要再去看介绍文字。但是做到如此不可避免要遇到很多问题: - 是否要正规描述资源? - 如何创建有帮助、自动化的命令行接口? - 如何做轮询、异步以及一些非标准的请求类型? - 如何处理没有做好RESTful映射的操作?

另一方面,优美的RESTful API不会轻易偏离RESTful架构设计原则。(A beautiful RESTful API on the other hand is one that does not deviate from the principles of RESTful architecture style too easily.)比如,一个很重要但人们不经常提到的设计因素是,用户完全自动发现API,人们可以通过web浏览器访问API,不需要外部的文档指导。这个问题我会在Forms详细描述。

我不会在文中介绍RESTful的基础知识,因为很多文章都介绍过了。如果你希望学习基础,我推荐阅读the Atom Publishing Protocol和Roy Fielding的博文

文中的观点都属个人,它们都是基于我在rhevm-api mailing list的讨论。我要感谢那些贡献的朋友:Mark McLoughlin, Michael Pasternak, Ori Liel, Sander Hoentjen, Ewoud Kohl van Wijngaarden, Tomas V.V. Cox还有一些我忘记的伙计。

译者说

以下几个问题需要重视: - 是否要正规描述资源? - 如何创建有帮助、自动化的命令行接口? - 如何做轮询、异步以及一些非标准的请求类型? - 如何处理没有做好RESTful映射的操作?