RESTful API设计指南

引言

本文记载论了我对如何设计完美RESTful API的个人想法。经验来源于我两次深入理解红帽虚拟化产品的RESTful API。在设计API的现实工作中，我们不得不去解决上述描述的一些问题。添加一些no-RESTful或者RPC风格API到工程中并不是我们期望看到的。

个人而言，实际工作中的RESTful API并不是教科书似的解决问题，他解决的是现实工作中不可避免的问题，比如说资源是否应该规范会地被描述，如何创建有用和自动命令行界面、如何做轮询、异步和其他非标准类型的请求，及其面对不合理RESTful映射时应有的操作。

另一方面，一个完美的RESTful API是不会轻易地偏离RESTful架构风格的原则的。其中一个重要的设计元素：不要一层不变，应该是API使用者完全可以不假思索地得到。以便这些API可以被网民在没有API文档的情况下使用。我将在Forms中继续深入讨论该问题。

既然有那么多文章讨论REST，那么本文将不再讨论REST的一些基础知识。对于REST的描述，我们可以阅读Atom发布协议和罗伊・菲尔丁的这篇博客。

本文所提到的观点虽然属于我个人的，但是这些观点都是在rhevm-api mailing list中所得的。在此向那些作出贡献的和任然在贡献想法的人表示衷心的感谢，比如：Mark McLoughlin, Michael Pasternak, Ori Liel, Sander Hoentjen, Ewoud Kohl van Wijngaarden, Tomas V.V. Cox 等等。