浅谈 Web API 的设计与开发

Question

API 是 Application Programming Interface 的缩写。Web API 是使用了 http 协议，所以需要通过 URI 信息来指 定端点，从而获取相应的数据。

端点的设计与请求的形式

在 Web API 的语境中，端点是指用于访问 API 的 uri。端点的形式是 uri，要探讨什么是优秀的uri设计，有一个非常重要的原则：

容易记忆，URI 包含的功能一目了然

1、短小便于输入的URI
2、人可以读懂的URI
3、没有大小写混用的URI（一般标准的做法是全部使用小写）
4、修改方便的URI
5、不会暴露服务器端架构的URI
6、规则统一的URI

http 方法总结

GET 方法

GET 方法一般用于获取URI指定的资源（信息）。因此，当人们使用GET方法访问时，一般不会修改服务器上已有的资源（当然，已读/未读 最后访问日期等资源属性会因GET操作而自动更新，属于例外）。因此，禁止编写通过 GET 方法修改服务器端信息的处理。

POST 方法

POST 方法与 GET 方法成对使用。一般认为 GET 方法用于获取信息，而 POST 方法则用于更新信息，但其实这样的理解任然存在一些偏差。

POST方法的初衷是发送附属于指定URI的新建资源信息，简而言之，该方法用于向服务器端注册新建的资源。信息的更新、删除等操作则通过其它HTTP方法 来完成。但是，由于HTML4.0的表单中method属性只支持GET与POST两种方法，因此使用表单从浏览器提交信息时，渐渐的连更新、删除在内德操作都用POST方法 来实现了。

虽然HTML5的草案中加入了表单允许使用PUT及DELETED方法的规范，但最终还是将该内容删除了。但由于web api基本不涉及使用表单通过浏览器进行访问，并且确定了客户端访问的意图后更方便后续工作，因此使用PUT方法和DELETED方法更容易理解。

PUT 方法

PUT 方法和 POST 方法相同，都可用于对服务器的信息进行更新，但二者URI的指定方式有所不同。

POST 方法发送的数据“附属”于指定的URI，附属表示从属于URI之下。以文件系统为例，把文件放入目录后，文件就成了目录的附属部分。因此，对文件目 录或分类目录等表示数据集合的URI进行POST 操作后，就会产生从属于原有集合的新数据。

PUT 方法则是指定需要更新的资源 URI 本身，并对其内容进行覆盖。如果 URI 资源已经存在，PUT 操作就意味着对该资源进行更新。虽然 HTTP 协议定义了当所 指定的资源不存在时，可以通过PUT 操作发送数据，生成新的资源，但 Web API 一般只用 PUT 方法来更新数据。

另外，PUT会用发送的数据完全替换原有的资源信息。如果只是更新资源的某部分数据，可以使用PATCH方法来实现。

DELETED 方法

顾名思义，DELETED 方法用于删除指定的资源，具体便是删除指定URI所描述的资源。

PATCH 方法

PATH 方法和 PUT 方法相同，都用于更新指定的资源。PUT 方法会用发送的数据替换原有的资源信息，PATCH 方法只会更新原有资源中的部分信息。

不使用空格及需要编码的字符

当 URI 里存在无法直接使用的字符时，需要用到一种名为 百分号编码 的方法对这些字符进行处理。换言之，就是使用用附加有%的字符进行标记，如 %E3%81%82。但是在 API 的端点中则应避免使用这些百分号编码的字符。原因非常简单，因为如果用了这些字符，就会导致无法一眼看出该端点描述的是什么。