随着技术不断的发展,越来越多的web应用采用前后端分离的技术,服务端通过API提供服务。随着服务的演进,一套完整的服务规范RESTful API就出现了。

一、RESTful API中常见的HTTP请求方法:

-GET:从服务器读取资源(Read)
-POST:创建资源(Create)
-PUT:更新资源(Update)
-PATCH:更新资源,通常用于更新部分资源(Update)
-DELETE:删除资源(Delete)

请求/响应资源类型:Content-Type 必须为application/jsonapplication/xml

示例:

#请求
POST https://houger.cn/orders HTTP/1.1
{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

#响应
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 57

二、请求状态码分析

对于GET请求,如果请求服务器成功,HTTP响应状态码应该设置为 200,如果请求资源未找到,此时应该返回404状态码。

对于POSTPUT请求,创建资源成功,返回201状态码

DELETE操作成功,返回状态码204 ,我们总结如下表格:

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

在API请求中我们我们基本上是用不到3xx状态码,比如301302它们代表url的重定向,不适用于API

4xx状态码表示客户端请求错误,常见错误分析:

状态码 表示含义
400 Bad request 服务器不理解客户端的请求,未做任何处理
401Unauthorized 用户未提供身份验证凭据,或者没有通过身份验证
403 Forbidden 用户没有权限访问服务器资源(用户是通过auth认证后请求)
404 Not Found 请求的资源不存在
405 Method Not Allowed 请求方法不被允许
415 Unsupported Media Type 客户端要求返回的数据格式不支持
422 Unprocessable Entity 客户端上传的附件无法处理,请求失败
429 Too Many Requests 客户端的请求次数超过限额

5xx的状态码,表示服务器端出现了问题,此时问题的具体信息是不能暴露给客户端的。最常用的两个状态码:

500 Internal Server Error: 服务器端故障;

503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态

三、API设计建议:

  1. REST是面向资源的,所以我们设计URL不要使用动词,采用名词 ,如:/goods/GET:/goods/POST:/goods/
  2. 在代码层,HTTP请求方法映射的CURD操作为:GET:Read, POST:Create, PUT 和PATCH:Update, DELETE:Delete
  3. 不要返回文本信息,必须指定响应类型即:Content-Typeapplication/json,某些场合applicaion/xml
  4. URL使用复数。尽管资源名词是否应使用复数单数形式可能很难决定,但是为了统一规范,我们还是建议使用复数。我们应该使用GET /articles/2/ ,不应该GET /article/2

  5. 请求发生错误时,不要返回200状态码,在响应体中返回详细错误信息,如下:

{
    "error": "Invalid payoad.",
    "detail": {
        "surname": "This field is required."
    }
}
  1. 不要多层URL嵌套使用:

请求的资源需要多级分类时,我们可会会写出多级的URL,比如我们获取某一个作者的文章:

GET: /authors/12/articles/

这种写法,很容易让用户误解,它到底是请求authors还是articles。我们建议URL+params形式来编写

我们改造如下:

GET: /articles/?author_id=12

又比如分页查询信息:

GET: /articles/?page=1&page_size=10
  1. 区别使用 401403 状态码:
    • 当用户未能提供身份凭证时返回401 即,未经授权
    • 当用户通过身份认证,但是没有权限访问资源时 返回403,禁止访问

四、参考:
restful-api-design-13-best-practices


Leave Your Comment

电子邮件地址不会被公开。 必填项已用*标注