003-REST-REST API 快速提示

谁借莪１个温暖的怀抱￠ 2022-01-21 08:29 131阅读 0赞

无论技术上是 REST 还是不是 REST(根据前文提到的六个约束条件)，这里有一些推荐的类似 REST 的概念。这六个快速提示将带来更好，更实用的服务。

### 使用 HTTP 动词使你的请求一目了然 ###

API 使用者能够发送 GET, POST, PUT, DELETE 动词，这极大地增强了给定请求的清晰度。
    通常，四个主要 HTTP 谓词使用如下：
    GET:
        读取特定资源(通过标识符)或资源集合；
    PUT:
        更新特定资源(通过标识符)或资源集合。如果资源标识符是事先已知的，也可以用于创建特定资源；
    DELETE:
        通过标识符 remove/delete 特定资源；
    POST:
        创建一个新资源。对于不适合其它类别的操作，也是一个包罗万象的动词；
    
    注意：
        GET 请求不得更改任何底层资源数据。可能仍会发生更新数据的测量和跟踪，但 URI 标识的资源数据不应更改。

### 提供合理的资源名称 ###

制作出色的API是80％的艺术和20％的科学。创建表示合理资源的URL层次结构是艺术部分。拥有合理的资源名称（只是URL路径，例如/ customers / 12345 / orders）可以提高给定请求的清晰度。
    
        适当的资源名称为服务请求提供上下文，从而提高API的可理解性。资源通过其URI名称进行分层查看，为调用者提供友好，易于理解的资源层次结构，以便在其应用程序中使用。
    
    以下是一些URL路径（资源名称）设计的快速规则：
        - 在你的网址中使用标识符而不是在查询字符串中传递参数，使用 URL 查询字符串参数非常适合过滤，但不适用于资源名称；
            1. good: /users/12345
            2. poor: /api?type=user&id=23
        - 利用 URL 的分层特性来暗示结构；
        - 为你的 clients 而不是为你的数据设计；
        - 资源名称为名词，避免使用动词作为资源名称，以提高清晰度。使用 HTTP 方法指定请求的谓词部分；
        - 在 URL 段中使用复数形式，以使用集合隐喻使你的 API URI 在所有 HTTP 方法中保持一致：
            1. 推荐  : /customers/33245/orders/8769/lineitems/1
            2. 不推荐: /customers/33245/order/8769/lineitem/1
        - 避免在 URL 中使用集合措辞。例如'customer_list'作为资源。使用复数来表示集合隐喻(例如，customers vs customer_list);
        - 在 URL 段中使用小写，用下划线('_')或连字符('-')分隔单词。有些服务器会忽略大小写，所以最好清楚；
        - 保持网址尽可能短，尽可能少的网段；

### 使用 HTTP 响应码指示请求状态 ###

响应状态代码是 HTTP 规范的一部分。 它们中有很多可以解决最常见的情况。 本着使 RESTful 服务包含HTTP规范的精神，我们的 Web API 应该返回相关的 HTTP 状态代码。 例如，当成功创建资源时（例如，来自POST请求），API应该返回HTTP状态代码201.这里有可用的 [HTTP 状态代码列表](https://www.restapitutorial.com/httpstatuscodes.html)，其列出了每个的详细描述。
        
    “Top 10” HTTP响应状态代码的建议用法如下：
        - 200 OK:
            一般成功状态码。这是最常见的状态码，用于表示请求成功；
        - 201 CREATED:
            成功创建(POST, PUT)。将 Location header 设置为包含指向新创建的资源的链接(POST)。响应主体内容可能存在也可能不存在；
        - 204 NO CONTENT:
            表示成功，但响应正文中没有任何内容，通常用于 DELETE 和 PUT 操作；
        - 400 BAD REQUEST:
            完成请求是的一半错误会导致无效状态。域验证错误，缺少数据等；
        - 401 未经授权：
            缺少或无效的身份验证 token的错误代码响应；
        - 403 FORBIDDEN：
            当用户未被授权执行操作或资源由于某种原因(例如时间限制)不可用时的错误码；
        - 404 NOT FOUND:
            在找不到所请求的资源时使用，是否不存在，或者是否存在 401 或 403，出于安全原因，服务想要屏蔽；
        - 405 METHOD NOT ALLOWED:
            用于指示请求的 URL 存在，但请求的 HTTP 方法不适用。例如，POST/users/12345，其中 API 不支持以这种方式创建资源(使用提供的 ID)。返回 405 时必须设置 Allow HTTP        header 以指示支持的 HTTP 方法。在前一种情况下，header 看起来像“Allow: GET, PUT, DELETE"
        - 409 CONFICT:
            每当通过履行请求导致资源冲突时。重复条目，例如尝试使用相同信息创建两个客户，以及在不支持联级删除时删除根对象等；
        - 500 INTERNAL SERVER ERROR:
            永远不要故意返回。服务器端抛出异常时的常规 catch-all 错误。仅将此用于调用者无法解决的错误。

### 提供 JSON 和 XML ###

除非您处于高度标准化且受监管的行业，需要XML，架构验证和命名空间，并提供 JSON 和 XML，除非成本惊人，否则请支持JSON支持。 理想情况下，让调用者使用 HTTP Accept header 在格式之间切换，或者只是在URL上将 .xml 的扩展名更改为 .json。
        
        请注意，一旦我们开始讨论 XML 支持，我们就会开始讨论用于验证，命名空间等的模式。除非您的行业需要，否则请尽量避免支持所有这些复杂性。 JSON 旨在简化，简洁和实用。 如果可以的话，让你的 XML 看起来像那样。
        
        换句话说，使返回的 XML 更像 JSON  - 简单易读，不存在架构和命名空间细节，只有数据和链接。 如果它最终比这更复杂，那么 XML 的成本将是惊人的。 根据我的经验，过去几年中没有人使用过 XML 响应，消费太昂贵了。
        
        请注意，如果您需要这样的东西，[JSON-Schema](https://json-schema.org/) 提供了架构式验证功能。

### 创建细粒度资源 ###

在开始时，最好创建模拟系统的底层应用程序域或数据库体系结构的 API。 最终，您将需要使用多个底层资源的聚合服务来减少干扰。 但是，稍后从单个资源创建更大的资源比从较大的聚合创建细粒度或单个资源要容易得多。 让自己轻松一点，从易于定义的小型资源开始，为这些资源提供 CRUD 功能。 您可以稍后创建那些 use-case-iruebted(面向用例)，减少 chattiness-reducing(繁琐降低) 的资源。

### 考虑连接性 ###

REST的原则之一是连通性 - 通过超媒体链接（搜索 HATEOAS）。 虽然没有它们，服务仍然有用，但在响应中返回链接时，API 会变得更具自我描述性和可发现性。 至少，“自我”链接引用会通知客户端如何检索数据。 此外，利用 HTTP Location header 包含通过 POST（或PUT）创建资源的链接。 对于在支持分页的响应中返回的集合，“first”，“last”，“next”和“prev”链接至少是非常有用的。
        
    关于链接格式，有很多。 HTTP Web链接规范（[RFC5988](https://tools.ietf.org/search/rfc5988)）解释了如下链接：
    链接是由国际化资源标识符（IRI）[[RFC3987](https://tools.ietf.org/search/rfc3987)]标识的两个资源之间的类型连接，包括：
        - 上下文 IRI；
        - 链接关系类型；
        - 目标 IRI，and；
        - 可选地目标属性；
    
        链接可以被视为“ {context IRI} 在 {target IRI} 具有 {relation type} 资源的形式的声明，其具有{target attributes} ”。
        
        至少，按照规范中的建议放置 HTTP 链接头中的链接，或者在 JSON 表示中包含此 HTTP 链接样式的 JSON 表示（例如Atom样式链接，请参阅：[RFC4287](https://tools.ietf.org/search/rfc4287#section-4.2.7)）。 之后，随着 REST API变得更加成熟，您可以在更复杂的链接样式中进行分层，例如 [HAL + JSON](https://stateless.co/hal_specification.html)，[Siren](https://github.com/kevinswiber/siren)，[Collection + JSON](https://amundsen.com/media-types/collection/)， 和 / 或 [JSON-LD](https://json-ld.org/) 等。