好RESTful API的设计原则

摘要: 好RESTful API的设计原则

好RESTful API的设计原则

Status Codes

状态码

It is very important that as a RESTful API, you make use of the proper HTTP Status Codes; they are a standard after all! Various network equipment is able to read these status codes, e.g. load balancers can be configured to avoid sending requests to a web server sending out lots of 50x errors. There are a plethora of HTTP Status Codes to choose from, however this list should be a good starting point:

对于一个RESTful API来说很重要的一点就是要使用HTTP的状态码，因为它们是HTTP的标准。很多的网络设备都可以识别这些状态码，例如负载均衡器可能会通过配置来避免发送请求到一台web服务器，如果这台服务器已经发送了很多的50x错误回来。这里有大量的HTTP状态码可以选择，但是下面的列表只给出了一些重要的代码作为一个参考：

200 OK – [GET]

The Consumer requested data from the Server, and the Server found it for them (Idempotent)

客户端向服务器请求数据，服务器成功找到它们

201 CREATED – [POST/PUT/PATCH]

The Consumer gave the Server data, and the Server created a resource

客户端向服务器提供数据，服务器根据要求创建了一个资源

204 NO CONTENT – [DELETE]

The Consumer asked the Server to delete a Resource, and the Server deleted it

客户端要求服务器删除一个资源，服务器删除成功

400 INVALID REQUEST – [POST/PUT/PATCH]

The Consumer gave bad data to the Server, and the Server did nothing with it (Idempotent)

客户端向服务器提供了不正确的数据，服务器什么也没做

404 NOT FOUND – [*]

The Consumer referenced an inexistant Resource or Collection, and the Server did nothing (Idempotent)

客户端引用了一个不存在的资源或集合，服务器什么也没做

500 INTERNAL SERVER ERROR – [*]

The Server encountered an error, and the Consumer has no knowledge if the request was successful

服务器发生内部错误，客户端无法得知结果，即便请求已经处理成功

Status Code Ranges

状态码范围

The 1xx range is reserved for low-level HTTP stuff, and you’ll very likely go your entire career without manually sending one of these status codes.

The 2xx range is reserved for successful messages where all goes as planned. Do your best to ensure your Server sends as many of these to the Consumer as possible.

The 3xx range is reserved for traffic redirection. Most APIs do not use these requests much (not nearly as often as the SEO folks use them ;), however, the newer Hypermedia style APIs will make more use of these.

The 4xx range is reserved for responding to errors made by the Consumer, e.g. they’re providing bad data or asking for things which don’t exist. These requests should be be idempotent, and not change the state of the server.

The 5xx range is reserved as a response when the Server makes a mistake. Often times, these errors are thrown by low-level functions even outside of the developers hands, to ensure a Consumer gets some sort of response. The Consumer can’t possibly know the state of the server when a 5xx response is received, and so these should be avoidable.

1xx范围的状态码是保留给底层HTTP功能使用的，并且估计在你的职业生涯里面也用不着手动发送这样一个状态码出来。

2xx范围的状态码是保留给成功消息使用的，你尽可能的确保服务器总发送这些状态码给用户。

3xx范围的状态码是保留给重定向用的。大多数的API不会太常使用这类状态码，但是在新的超媒体样式的API中会使用更多一些。

4xx范围的状态码是保留给客户端错误用的。例如，客户端提供了一些错误的数据或请求了不存在的内容。这些请求应该是幂等的，不会改变任何服务器的状态。

5xx范围的状态码是保留给服务器端错误用的。这些错误常常是从底层的函数抛出来的，并且开发人员也通常没法处理。发送这类状态码的目的是确保客户端能得到一些响应。收到5xx响应后，客户端没办法知道服务器端的状态，所以这类状态码是要尽可能的避免。