RESTful API设计系列一：简介

说明

• 原文链接
• 翻译：@adolphlwq
• 项目地址
• 

简介

这篇文章里，我尝试写下我心中的、真正优美的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映射的操作？