由于RESTful基于web的服务的性质，标准化文档应该是相当容易的。它应该列出可用资源、相应的URI、允许的方法、内容类型和描述可用操作。你有任何建议吗？
这种列举资源URI的方式完全是错误的文档REST服务的方式。你不应该枚举资源的URI，因为这会鼓励客户端将这些URI硬编码到客户端代码中。这会在客户端和服务器之间创建不必要的耦合。URI应该根据从服务根URI导航发现。只有根URI应该被记录。文档应该集中描述返回的表述中包含哪些信息和链接。如果您从根URI返回的表述开始，就可以描述媒体类型以及该文档可能提供的链接。
使用某种别名来创建客户端和服务器之间的间接层非常重要。如果按照atom:link标准定义链接，则rel属性成为标识符。但是，还有其他定义链接的方法，例如在HTML中嵌入图像的方式。图像标签可以具有Id和href。Id标签应该用于标识您希望访问其URL的图像。
最终结果是，在某个表述的上下文中定义了API的所有端点。返回表示和连接它们的链接定义了完整的API。那么，您可能会问，有什么区别？为什么不只创建端点列表呢？以下是一些原因：
可更改的URI空间因为这些链接是通过别名由客户端访问的，所以即使您完全更改站点的整个URL结构，也不会影响客户端。这就使得无尽的“如何构建我的分层URL结构最好”等问题基本上不成立。您可以尝试一种方式，如果不起作用，只需更改它，就不会破坏任何客户端代码或必须更改任何文档！
动态分配
您不仅可以更改URI的路径部分，还可以更改主机。想象一下，如果您的应用程序的使用量比预期的要多得多，您可以轻松地将所有图像或视频资源的主机更改为指向另一个服务器。您甚至可以通过返回不同的主机来提供简单的负载平衡。由于RESTful API是无状态的，因此响应请求的服务器并不重要。该功能对许多场景非常有用：将HTTPS内容移动到专用服务器上，根据客户端位置地理分布请求，将应用程序的不同功能垂直分区到不同的服务器。
显式协议
仅因为表示可能返回链接，并不意味着它总是会这样做。服务器只能根据当前资源状态允许的链接返回。当与服务器资源交互时需要遵循特定协议时，这可以非常有帮助。客户端代码不需要理解协议的规则，只需向用户呈现服务器提供的可用链接即可。
你无法自动生成有趣的内容
大多数自动记录REST服务的尝试之所以无效，是因为统一接口消除了记录简单内容的必要性。一旦您了解HTTP（参见RFC2616），您就会了解API的所有机制。剩下的是真正有趣的特定于域的信息，无法生成。
看到好的一面，文档应该更短。任何额外的可用时间都应花在为常见情况提供如何导航API的示例上。
