摘要

Web API 是一种在 Web 应用程序之间交换数据的机制，它使得开发者可以轻松地在应用程序之间共享数据和服务。而 Web API 规范则是指定 Web API 的开发方式和数据交换方式的标准化规范。常用的 Web API 规范包括面向过程的 RPC、面向 RESTful 的 Web API 和 GraphQL 等。

RPC

Remote Procedure Call (RPC)是一种常用的计算机网络技术，用于在远程计算机上执行本地方法或函数。与传统的本地方法调用不同，RPC允许客户端在与远程服务器进行通信时直接执行远程方法，而不需要在本地进行额外的编译和安装。

在RPC里，客户端通常是把方法名和参数传递给服务器，然后服务器返回JSON或XML。

• 端点要包含被执行操作的名字

• 使用合理的HTTP动词，GET用于读取，POST用于其它类型。

REST

Representational State Transfer (REST) 是一种现今广泛使用的 Web API 设计风格。REST 是指通过使用表述性状态传递来管理 Web 应用程序中的状态。

REST（Representational State Transfer）的核心是资源，它是一个可以被标识的实体，通常有一个名称和地址。每个资源都可以被独立地识别、描述和操作，而不必知道它所属的系统或应用程序。因此，资源是REST架构的基础，是REST API设计和实现的核心概念。

REST API就是把数据以资源的形式暴露出来，并使用标准的HTTP方法来代表创建、读取、更新和删除资源等事务。

• 资源都是URL的一部分，例如/persons

• 针对每个资源通常都会有两个URL被实现：“/persons”表示资源的集合，“/person/321”表示特定的一个资源

• 在资源里，使用名词而不是动词，例如 /getUserInfo/123 这就不对了，应该是 /users/123

• HTTP方法表明了要执行的动作，不同的HTTP方法作用于同一个URL上可实现不同的功能：

• 创建 -- POST

• 读取 -- GET

• 整体更新 -- PUT

• 局部更新 -- PATCH

• 删除 -- DELETE

• 服务器会以HTTP状态码来响应请求，状态码分为2xx、3xx、4xx和5xx四类，分别表示成功、重定向、客户端错误和服务器端错误。其中2xx表示成功，3xx表示重定向，4xx表示客户端错误，5xx表示服务器端错误。

REST与RPC区别

REST和RPC都是用于实现客户端与服务器之间的通信的架构模式。但是它们的关注点不同。REST是一种基于资源的架构模式，强调在Web上通过URI定位资源，通过HTTP协议进行资源的读写操作。而RPC是一种基于动作的架构模式，强调在客户端和服务器之间传递请求和响应的过程，包括请求参数、返回值、错误信息等。简单来说，REST关注的是资源，而RPC关注的是请求和响应。

GraphQL

GraphQL 是一种现代化的 API 查询语言，它于2014年由 Facebook 推出。GraphQL 是一种用于创建 RESTful 服务的查询语言，它可以通过请求一个 API 而获得需要的所有数据，而不是像 RESTful API 一样请求单个资源。

GraphQL为客户端提供了更大的控制权，使得客户端能够明确指定需要获取的数据结构。而服务器则会根据客户端的请求，返回完全匹配的数据结构。这种灵活的方式能够更有效地减少数据冗余，并且能够帮助开发者更快速地构建高质量的应用程序。

与REST和RPC不同，GraphQL API只需要一个端点来提供数据。它也不需要使用不同的HTTP动词，只需要使用POST方法。在JSON的body中，你需要明确指定要执行查询还是修改操作。

什么时候应该用哪种Web API呢？

• 针对CRUD类的API，使用REST

• 针对暴露很多动作的API，使用RPC

• 当你需要查询的灵活性以及维护的连续性时，使用GraphQL

  
  

HTTP协议规范

常见状态码及含义

200 - 请求成功，已经正常处理完毕

201 - 创建成功

301 - 请求永久重定向，转移到其它URL

302 - 请求临时重定向

304 - 请求被重定向到客户端本地缓存

400 - 客户端请求存在语法错误

401 - 客户端请求没有经过授权

403 - 客户端的请求被服务器拒绝，一般为客户端没有访问权限

404 - 资源未找到，客户端请求的URL在服务端不存在

500 - 服务端出现异常

MIME类型对应列表

GET和POST的区别

• GET在浏览器回退时是无害的，而POST会再次提交请求。

• GET产生的URL地址可以被Bookmark，而POST不可以。

• GET请求会被浏览器主动cache，而POST不会，除非手动设置。

• GET请求只能进行url编码，而POST支持多种编码方式。

• GET请求参数会被完整保留在浏览器历史记录里，而POST中的参数不会被保留。

• GET请求在URL中传送的参数是有长度限制的，而POST则没有。对参数的数据类型GET只接受ASCII字符，而POST即可是字符也可是字节。

• GET比POST更不安全，因为参数直接暴露在URL上，所以不能用来传递敏感信息。

• GET参数通过URL传递，POST放在Request body中。

RESTful URL请求格式与传统请求格式比较如下