RESTful最佳实践——三、REST快速提示

REST快速提示

（根据上面提到的六个原则）不管在技术上是不是RESTful的，这里有一些类似REST概念的建议。遵循它们，可以实现更好、更有用的服务：

使用http动词表示一些含义

任何API的使用者能够发送GET、POST、PUT和DELETE请求，它们很大程度明确了所给请求的目的。同时，GET请求不能改变任何潜在的资源数据。测量和跟踪仍可能发生，但只会更新数据而不会更新由URI标识的资源数据。

合理的资源名

合理的资源名称或者路径（如/posts/23而不是/api?type=posts&id=23）可以更明确一个请求的目的。使用URL查询串来过滤数据是很好的方式，但不应该用于定位资源名称。

适当的资源名称为服务端请求提供上下文，增加服务端API的可理解性。通过URI名称分层地查看资源，可以给使用者提供一个友好的、容易理解的资源层次，以在他们的应用程序上应用。资源名称应该应该是名词，避免为动词。使用HTTP方法来指定请求的动作部分，能让事情更加的清晰。

XML和JSON

建议默认支持json，并且，除非花费很惊人，否则就同时支持json和xml。在理想情况下，让使用者仅通过改变扩展名.xml和.json来切换类型。此外，对于支持ajax风格的用户界面，一个被封装的响应是非常有帮助的。提供一个被封装响应，在默认的或者有单独扩展名的情况下，例如：.wjson和.wxml，表明客户端请求一个被封装的json或xml响应（请参见下面的封装响应）。

“标准”中对json的要求很少。并且这些需求只是语法性质的，无关内容格式和布局。换句话说，REST服务端调用的json响应是协议的一部分–没在标准中没有相关描述。更多关于json数据格式可以在http://www.json.org/上找到。

在REST服务端使用xml，xml的标准和惯例只有关于使用语法正确的标签和文本。特别地，命名空间不是，也不应该是被使用在REST服务端的上下文中。xml的返回更类似于json–简单、容易阅读，没有模式和命名空间细节呈现–仅仅是数据和链接。如果它比这更复杂，看到这个提示（xml和json）的第一段–使用xml的成本是惊人的。然而鉴于我们的经验，很少人使用xml响应。在它被完全淘汰之前，这是最后一个可被肯定的地方。

创建适当粒度的资源

开始的时候，模拟底层应用程序域或数据库系统的体系结构更容易去创建API。最终，你将会希望集成服务–利用多项底层资源减少通信量。在创建独立的资源之后再创建更大粒度的资源，比从更大的合集中创建较大的粒度资源来得更加容易。提供这些资源的CRUD（增删改查）功能，从使用小的、容易定义的资源，可以使创建资源变得容易。随后，你可以创建这些基于用例和减少通信量的资源。

考虑连通性

REST的原理之一就是连通性–通过超媒体链接实现。当在响应中返回链接时，api变的更具有自描述性，然而在没有它们时服务端依然可用。至少，接口本身可以为客户端提供如何检索数据的参考。此外，在通过POST方法创建资源时，还可以利用头位置包含一个链接。对于响应中支持分页的集合，“first”、 “last”、“next”、和“prev”链接至少是非常有用的。

---

原文如下

REST Quick Tips

Whether it’s technically RESTful or not (according to the six constraints mentioned above), here are a few recommended REST-like concepts that will result in better, more usable services:

Use HTTP Verbs to Mean Something

Any API consumer is capable of sending GET, POST, PUT, and DELETE verbs, and they greatly enhance the clarity of what a given request does. Also, GET requests must not change any underlying resource data. Measurements and tracking may still occur, which updates data, but not resource data identified by the URI.

Sensible Resource Names

Having sensible resource names or paths (e.g., /posts/23 instead of /api?type=posts&id=23) improves the clarity of what a given request does. Using URL query-string parameters is fantastic for filtering, but not for resource names.

Appropriate resource names provide context for a service request, increasing understandability of the service API. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily-understood hierarchy of resources to leverage in their applications.

Resource names should be nouns—avoid verbs as resource names. It makes things more clear. Use the HTTP methods to specify the verb portion of the request.

XML and JSON

Favor JSON support as the default, but unless the costs of offering both JSON and XML are staggering, offer them both. Ideally, let consumers switch between them by just changing an extension from .xml to .json. In addition, for supporting AJAX-style user interfaces, a wrapped response is very helpful. Provide a wrapped response, either by default or for separate extensions, such as .wjson and .wxml to indicate the client is requesting a wrapped JSON or XML response (see Wrapped Responses below).

JSON in regards to a “standard” has very few requirements. And those requirements are only syntactical in nature, not about content format or layout. In other words, the JSON response to a REST service call is very much part of the contract—not described in a standard. More about the JSON data format can be found at http://www.json.org/.

Regarding XML use in REST services, XML standards and conventions are really not in play other than to utilize syntactically correct tags and text. In particular, namespaces are not, nor should they be use in a RESTful service context. XML that is returned is more JSON like—simple and easy to read, without the schema and namespace details present—just data and links. If it ends up being more complex than this, see the first paragraph of this tip—the cost of XML will be staggering. In our experience few consumers uses the XML responses anyway. This is the last ‘nod’ before it gets phased out entirely.

Create Fine-Grained Resources

When starting out, it’s much easier to create APIs that mimic the underlying application domain or database architecture of your system. Eventually, you’ll want aggregate services—services that utilize multiple underlying resources to reduce chattiness. But it’s much easier to create larger resources later from individual resources than it is to create fine-grained or individual resources from larger aggregates. Make it easy on yourself and start with small, easily defined resources, providing CRUD functionality on those. You can create those use-case-oriented, chattiness-reducing resources later.

Consider Connectedness

One of the principles of REST is connectedness—via hypermedia links. While services are still useful without them, APIs become more self-descriptive when links are returned in the response. At the very least, a ‘self’ reference informs clients how the data was or can be retrieved. Additionally, utilize the Location header to contain a link on resource creation via POST. For collections returned in a response that support pagination, ‘first’, ‘last’, ‘next’ and ‘prev’ links at a minimum are very helpful.