1.3 REST最佳实践

REST作为一种架构风格，它不是标准，因此并没有一套确定的、公认的规则。尽管REST包含了6个用于指导设计出RESTful系统的约束，但在具体实现时，在很多细节上仍然会有多种多样的方式。不同的实现方式使系统具有不同的表现或不同的使用方式，因此在实现时，应遵循一些基本原则，也即最佳实践。

首先，在实现RESTful系统时，应正确地使用HTTP方法、HTTP消息头和HTTP状态码。

在上一节我们已经看到，HTTP协议对HTTP方法、消息头、响应码等都有详尽且明确的定义，当设计RESTful API时，应遵循其定义。比如，对于HTTP方法，应使用GET方法获取资源，使用POST方法创建资源。如果没有遵循这些方法的定义，则可能会出现使用POST方法获取、删除资源等情况，这是因为当客户端发送一个POST请求时，服务器上相应的方法不是创建资源，反而是获取或删除资源。

同样，客户端与服务端在进行请求与响应时，应正确地使用HTTP消息头。比如，当客户端要想指定资源的预期表述格式时，应使用Accept消息头，而非其他方式，这也正是该消息头的意义所在。

当服务器向客户端返回响应时，也应正确地使用HTTP状态码。比如，当操作成功却不需要返回响应正文时，应使用返回204 No Content（删除或更新资源）或201 Created（创建资源）。又如，当服务器不支持客户端指定的资源表述格式时，应返回406 Not Acceptable状态码。

由此可以看出，理解HTTP协议并正确地使用它对于设计出规范的RESTful API非常重要。除了这些原则以外，在设计资源的URI时也应注意下列原则。

使用名词的复数表示一个资源集合，如api.domain.com/users。

使用斜线“/”用来表示资源之间的层次关系，如api.domain.com/users/1234/orders。

对资源的增、删、查、改等操作名称不应包含在URL中，反之应正确使用HTTP方法。比如，GET /deleteuser/1234（错误），DELETE users/1234（正确）。

如果一个操作无法对应到资源的某个操作上，此时可以适当地在URI中包含动词，但仍然应该基于一个资源的标识符，如下所示。

PUT /users/1234/set-admin
DELETE /users/1234/set-admin

查询字符串可以用来对资源进行筛选、搜索或分页查询等操作，如下所示。

GET /users?role=admin
GET /users?searchQuery=abc
GET /users?pageSize=25&pageNumber=2

URI应使用小写字母。

URI中可以使用中划线“-”来增加其可读性，如下例中使用“-”来代替空格。http://api.domain.com/blogs/this-is-my-first-post

URI中不应使用下划线。在浏览器或高级编辑器中，URI通常会带有下划线，以表示它是可点击的，这个下划线将会使URI中的下划线不可见，可以使用中划线“-”替代下划线。

URL末尾不应包含斜线“/”，尽管URL末尾包含了“/”并不影响其功能，然而末尾的“/”没有任何意义甚至还有可能会造成歧义，因此服务器返回给客户端的URL末尾不应包含“/”。