【布道 API】API 设计应该了解的 HTTP 方法和特性

在 REST API 设计理念里面对于资源的具体操作使用 HTTP 动词（方法），昨天在《API端点/资源命名最佳实践》介绍了端点的命名，今天来介绍在 REST API 设计中经常用到的 HTTP 方法，这些方法类似于字母表很常用。开发人员通常只使用 GET、PUT 、DELETE 或 POST，HTTP 官方介绍了 39 个 HTTP 请求方法及每个方法适合的场景。在本文中，介绍在 REST API 设计中常用的 HTTP 请求方法和特性。

1.资源获取

最熟悉的就是 GET 和 HEAD，被用作以特定的方式获取资源的场合。这是最容易理解的方法，也是最常用的。

GET

GET 方法用于请求获取特定的资源，GET 请求应该只用于获取数据。

HEAD

HEAD 反映了另一个方法的一些功能，同时解锁了更多的可能性。HEAD 从给定资源请求 GET 响应，但是没有响应体，这看上去比较简单，但它允许更大的灵活性来为其他 API 进行扩展，例如可以将资源的 HEAD 传递给另一个请求以模拟不同的请求环境，这对测试和故障排除非常有帮助。

2.资源修改

有很多方法可以从根本上改变资源，这些方法可以包括放置资源、替换目标资源，甚至更新有关资源的属性。

PUT

PUT 在某种程度上与 GET 截然相反。GET 请求特定资源，PUT 将该资源放置在远程目录中。应该注意的是，使用 PUT 时，当资源不存在的时候就就是创建，已存在就是覆盖，

PATCH

PATCH 被用来部分修改目标资源，换句话说，当 PUT 将资源放置在目标服务中时，PATCH 是修改该资源，而不是替换它，这对于更新文件或者版本很实用。

3.资源删除

DELETE 很直观的就知道是删除目标资源。删除方法的通常的响应是简单地回复 OK 状态 —— 资源被删除或者没有。

4.资源创建

POST 用于创建目标资源，允许通过 API 提交一个属性或者实体。

5.资源环境

并不是对资源的每次更改都必须是对资源内容的更改，有两个方法与资源环境的交互比资源本身更多。

TRACE

TRACE 是执行消息回送测试的方法，这个测试允许查看到目标资源的路径，确定潜在的故障点。这是一个非常强大的工具，虽然它可能很简单，因为它只是反映了资源的基本路径。

CONNECT

CONNECT 是一个创建与资源的通信而不是直接与所述资源交互的方法，CONNECT 用于建立与目标资源的服务器连接的通道。通常的作用就是把服务器作为跳板（将服务器作为代理），让服务器代替用户去访问其它网页，之后把数据原原本本的返回给用户。

幂等性

幂等性（Idempotence）是 HTTP 方法的重要特性之一，从定义上看，HTTP 方法的幂等性是指一次和多次请求某一个资源应该具有同样的响应结果。根据幂等性的定义只有GET、HEAD、PUT和DELETE是具有幂等性，POST和PATCH不具有幂等性。

安全性

安全性是 HTTP 方法的另一特性，和幂等性不一样，安全方法根本不会改变服务器的状态，根据这个定义只有GET、HEAD 是安全的。

下面是上述方法的安全性和幂等性情况：

总结

深入理解这些方法、它们的幂等性和它们的安全性是 API 设计的基础。