restful服务接口规范

推荐2篇blog，对于理解restful很有帮助

HTTP Methods

HTTP Method Description
GET To retrieve a resource.
POST To create a resource, or to execute a complex operation on a resource.
PUT To update a resource.
DELETE To delete a resource.
PATCH To perform a partial update to a resource.

状态码

Range Meaning
2xx Successful execution. It is possible for a method execution to succeed in several ways. This status code specifies which way it succeeded.
4xx Usually these are problems with the request, the data in the request, invalid authentication or authorization, etc. In most cases the client can modify their request and resubmit.
5xx Server error: The server was not able to execute the method due to site outage or software defect. 5xx range status codes SHOULD NOT be utilized for validation or logical error handling.
Status Code Description
200 OK Generic successful execution.
201 Created Used as a response to POST method execution to indicate successful creation of a resource. If the resource was already created (by a previous execution of the same method, for example), then the server should return status code 200 OK.
202 Accepted Used for asynchronous method execution to specify the server has accepted the request and will execute it at a later time. For more details, please refer Asynchronous Operations.
204 No Content The server has successfully executed the method, but there is no entity body to return.
400 Bad Request The request could not be understood by the server. Use this status code to specify:
<ul><li>The data as part of the payload cannot be converted to the underlying data type.</li><li>The data is not in the expected data format.</li><li>Required field is not available.</li><li>Simple data validation type of error.</li></ul>
401 Unauthorized The request requires authentication and none was provided. Note the difference between this and 403 Forbidden.
403 Forbidden The client is not authorized to access the resource, although it may have valid credentials. API could use this code in case business level authorization fails. For example, accound holder does not have enough funds.
404 Not Found The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available. For example, it may be that no data exists in the database at that key.
405 Method Not Allowed The server has not implemented the requested HTTP method. This is typically default behavior for API frameworks.
406 Not Acceptable The server MUST return this status code when it cannot return the payload of the response using the media type requested by the client. For example, if the client sends an Accept: application/xml header, and the API can only generate application/json, the server MUST return 406.
415 Unsupported Media Type The server MUST return this status code when the media type of the request's payload cannot be processed. For example, if the client sends a Content-Type: application/xml header, but the API can only accept application/json, the server MUST return 415.
422 Unprocessable Entity The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
429 Too Many Requests The server must return this status code if the rate limit for the user, the application, or the token has exceeded a predefined value. Defined in Additional HTTP Status Codes RFC 6585.
500 Internal Server Error This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. A 500 response indicates a server-side software defect or site outage. 500 SHOULD NOT be utilized for client validation or logic error handling.
503 Service Unavailable The server is unable to handle the request for a service due to temporary maintenance.

上面的list从paypal抄来的，容易有分歧的几个点明确下

  • GET成功是200
  • POST创建一个资源，是201
  • 202表示接受了任务，进入后台处理了
  • 401表示未登录，403表示已登录但无权限
  • 400和422的区分不是太明显；400表示一般的参数错误错误，比如格式错误、缺少参数等；而422表示参数检测通过之后，后续的业务处理不支持; 实际上422早先是没有的，后边扩展来的
  • 405 method不支持，比如只支持get的发了post请求
  • 406表示不支持client要求的响应格式，比如client要求返回json，而服务端只支持xml
  • 415表示request body的content-type不支持

自定义状态码

根据 https://tools.ietf.org/html/rfc2616#section-6.1.1 ， status code原则上是可以进行扩展的

https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml 这里列出了http已分配和未分配的status code

我们可以选取 452-499作为我们的扩展区间，用于表示通用的client错误

需留意： 这里定义的status，一定是面向整个api全局，和具体业务无关的，client收到这些status，要使用明确的、一致的处理方式

url resource规范

restful class 规范

  • 统一使用单数
  • 对于需要区分单复数的场景，用 "Item" 后缀指代单数，例如订单列表类名用Order，而订单详情用OrderItem

api 参数和返回值规范

  • 返回值格式：直接返回资源对象
  • 返回一个列表资源时，key名固定用 "items"；返回单个资源则无需再包一层

参考

https://apiguide.readthedocs.io/en/latest/build_and_publish/use_RESTful_urls.html

https://github.com/paypal/api-standards/blob/master/api-style-guide.md

https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md

https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成，浏览时请结合常识与多方信息审慎甄别。
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

友情链接更多精彩内容