build api - yaokun123/php-wiki GitHub Wiki

web api的设计与开发

一、什么是Web api

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方法总结

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

  2. POST方法：POST方法与GET方法成对使用。一般认为GET方法用于获取信息，而POST方法则用于更新信息，但其实这样的理解任然存在一些偏差。 POST方法的初衷是发送附属于指定URI的新建资源信息，简而言之，该方法用于向服务器端注册新建的资源。信息的更新、删除等操作则通过其它HTTP方法 来完成。
    但是，由于HTML4.0的表单中method属性只支持GET与POST两种方法，因此使用表单从浏览器提交信息时，渐渐的连更新、删除在内德操作都用POST方法 来实现了。虽然HTML5的草案中加入了表单允许使用PUT及DELETED方法的规范，但最终还是将该内容删除了。
    但由于web api基本不涉及使用表单通过浏览器进行访问，并且确定了客户端访问的意图后更方便后续工作，因此使用PUT方法和DELETED方法更容易理解。

  3. PUT方法：PUT方法和POST方法相同，都可用于对服务器的信息进行更新，但二者URI的指定方式有所不同。
    POST方法发送的数据“附属”于指定的URI，附属表示从属于URI之下。以文件系统为例，把文件放入目录后，文件就成了目录的附属部分。因此，对文件目 录或分类目录等表示数据集合的URI进行POST操作后，就会产生从属于原有集合的新数据。
    PUT方法则是指定需要更新的资源URI本身，并对其内容进行覆盖。如果URI资源已经存在，PUT操作就意味着对该资源进行更新。虽然HTTP协议定义了当所 指定的资源不存在时，可以通过PUT操作发送数据，生成新的资源，但Web API一般只用PUT方法来更新数据。
    另外，PUT会用发送的数据完全替换原有的资源信息。如果只是更新资源的某部分数据，可以使用PATCH方法来实现。

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

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

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

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

三、最大程度的利用HTTP协议规范