restful api的10个最佳实践

浅浅的花香味﹌ 2023-06-04 04:49 80阅读 0赞

Web API在过去的几年里非常盛行，因为它有着语法简单、规范化和轻量级的优点，因为得到广泛的推崇，很多过往的技术手段都慢慢转换为使用Web API来开发。而Web API通常使用的设计方式是RESTful（Representational State Transfer，表述性状态转移），它使用了典型的HTTP方法，诸如GET、POST、PUT和DELETE来对资源进行管理和交互。

这里列出设计RESTful API的10个最佳实践。

**1.在API中使用名词，而不是动词。**

在RESTful中，API描述的应该是资源，而不是动作，因此在API应使用名词去描述资源，而不是动词用动词去描述动作。

<table> 
 <thead> 
  <tr> 
   <th style="text-align:left;"> 
    <div> 
     <strong>RESOURCE</strong> 
    </div> </th> 
   <th style="text-align:left;"> 
    <div>
      GET:READ 
    </div> </th> 
   <th style="text-align:left;"> 
    <div> 
     <strong>POST:CREATE</strong> 
    </div> </th> 
   <th style="text-align:left;"> 
    <div> 
     <strong>PUT:UPDATE</strong> 
    </div> </th> 
   <th style="text-align:left;"> 
    <div> 
     <strong>DELTE:DELETE</strong> 
    </div> </th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td> 
    <div> 
     <p>/cars</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>返回一个car的列表</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>创建一个新的car</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>更新car的信息</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>删除所有的car</p> 
    </div> </td> 
  </tr> 
  <tr> 
   <td> 
    <div> 
     <p>/cars/yanggb</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>返回指定的car</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>Method not allowed(405)</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>更新指定的car的信息</p> 
    </div> </td> 
   <td> 
    <div> 
     <p>删除指定的car</p> 
    </div> </td> 
  </tr> 
 </tbody> 
</table>

而不是使用动词，比如下面的API是不推荐的：

/getAllCars 获取所有车辆
    /createNewCar 创建新的车辆
    /deleteAllRedCars 删除所有红色的车辆

**2.GET方法和查询参数不应该改变资源状态。**

GET方法的API应该是幂等的，即不应该改变资源的状态，无论请求多少次，返回的结果都是一致的。

如果要改变资源的状态，应该使用POST、PUT和DELETE方法。

**3.使用名词的复数形式。**

不要混合使用名词的单数和复数形式，而应该为所有的资源从一开始就保持使用复数形式。

/cars 替代 /car
    /users 替代 /user
    /products 替代 /product
    /settings 替代 /setting

**4.为关系使用子资源。**

假如资源连接到其他资源，则应该使用子资源的形式来设计API。

GET /cars/711/drivers 返回711车的驱动器列表
    GET /cars/711/drivers/4 返回711车的#4驱动

**5.使用HTTP头决定序列化格式。**

在客户端和服务端都需要知道使用什么格式来进行通信，这个格式应该在HTTP头中指定。

Content-Type：定义请求的格式。

Accept：定义允许的响应格式的列表。

**6.使用HATEOAS。**

HATEOAS（Hypermedia as the Engine of Application State）是REST架构风格中最复杂的约束，也是构建成熟REST服务的核心。它是一个指导原则，规定超文本链接应该被用于在API中创建更好的资源导航。

{
        "id": 711,
        "manufacturer": "bmw",
        "model": "X5",
        "seats": 5,
        "drivers": [{
            "id": "23",
            "name": "yanggb",
            "links": [{
                "rel": "self",
                "href": "/api/v1/drivers/23"
            }]
        }]
    }

在上面的返回结果中，包含了超文本链接资源的信息。

**7.为集合提供过滤、排序、字段选择和分页。**

过滤：为所有字段或者查询语句提供独立的查询参数。

GET /cars?color=red 返回红色车的列表
    GET /cars?seats<=2 返回两座车的列表

排序：允许跨越多字段的正序或者倒序排列。

GET /cars?sort=-manufactorer,+model 返回排序的车辆列表

字段选择：只列出需要的字段。一些情况下，只需要在列表中查询几个有标识意义的字段，并不需要从服务端把所有字段的值都请求出来，因此需要API支持选择查询字段的能力。这样也可以在一定程度上提高网络传输的性能与响应速度。

GET /cars?fields=manufacturer,model,id,color 返回需要的车辆信息字段的列表

分页：使用offset和limit来获取固定数量的资源结果，当其中一个参数没有出现时，应该提供各自的默认值，比如默认取第一页，或者默认取20条数据。

GET /cars?offset=10&limit=5 返回第10页的5条车辆记录列表
    GET /cars?&limit=5 返回前5条车辆记录列表
    GET /cars?&offset=5 返回第5页的车辆记录列表（默认单页数量）

**8.版本化API。**

确保强制实行API版本，并且不要发布一个没有版本的API。使用简单的序列数字，比如v1，避免使用2.5.0这样的形式（点分隔符）。

/blog/api/v1

**9.使用HTTP状态码处理错误。**

忽略错误处理的API是很难使用的，简单的返回500和调用堆栈是非常不友好的，同时这些错误信息在一定程度上来说也是无用的。

使用HTTP状态码

HTTP标准中提供了70多个状态来描述返回值，但是我们并不需要用到其中的全部，只需要了解其中一些比较常用的就可以了。

200 – OK – 一切正常
    201 – OK – 新资源已经被创建
    204 – OK – 资源删除成功
    
    304 – 没有变化，客户端可以使用缓存数据
    
    400 – Bad Request – 调用不合法，确切的错误应该在error payload中描述
    401 – 未认证，调用需要用户通过认证
    403 – 不允许的，服务端正常解析和请求，但是调用被回绝或者不被允许
    404 – 未找到，指定的资源不存在
    422 – 不可指定的请求体 – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失
    
    500 – Internal Server Error – 标准服务端错误，API开发人员应该尽量避开这种错误

使用error payloads

所有的请求异常都应该被映射到error payloads中。

{
        "errors": [{
            "userMessage": "Sorry, the requested resource does not exist",
            "internalMessage": "No car found in the database",
            "code": 34,
            "more info":"http://www.yanggb.com/blog/api/v1/errors/12345"
        }]
    }

**10.允许重写HTTP方法。**

一些代理只支持GET和POST方法。为了在这种限制下使用RESTful API（GET/POST/PUT/DELETE），则API需要重写HTTP方法。

比如可以使用自定义的X-HTTP-Method-Override HTTP头来重写POST方法。

"感情实在是场无法掌控的事，没有逻辑，没有规律，更没顺理成章的必然。"

转载于:https://www.cnblogs.com/yanggb/p/11399274.html