2018年01月07日 | api接口类型有哪些_API设计的基本要求

API 同时也是一种中间件，为各种不同平台提供数据共享。根据单个或分布式平台上不同软件应用程序间的数据共享性能，可以将 API 分为四种类型：

远程过程调用（RPC）：通过作用在共享数据缓存器上的过程（或任务）实现程序间的通信。

标准查询语言（SQL）：是标准的访问数据的查询语言，通过通用数据库实现应用程序间的数据共享。

文件传输：文件传输通过发送格式化文件实现应用程序间数据共享。

信息交付：指松耦合或紧耦合应用程序间的小型格式化信息，通过程序间的直接通信实现数据共享。

当前应用于 API 的标准包括 ANSI 标准 SQL API。另外还有一些应用于其它类型的标准尚在制定之中。API 可以应用于所有计算机平台和操作系统。这些 API 以不同的格式连接数据（如共享数据缓存器、数据库结构、文件框架）。每种数据格式要求以不同的数据命令和参数实现正确的数据通信，但同时也会产生不同类型的错误。因此，除了具备执行数据共享任务所需的知识以外，这些类型的 API 还必须解决很多网络参数问题和可能的差错条件，即每个应用程序都必须清楚自身是否有强大的性能支持程序间通信。相反由于这种 API 只处理一种信息格式，所以该情形下的信息交付 API 只提供较小的命令、网络参数以及差错条件子集。正因为如此，交付 API 方式大大降低了系统复杂性，所以当应用程序需要通过多个平台实现数据共享时，采用信息交付 API 类型是比较理想的选择。

API 与图形用户接口（GUI）或命令接口有着鲜明的差别：API 接口属于一种操作系统或程序接口，而后两者都属于直接用户接口。

有时公司会将 API 作为其公共开放系统。也就是说，公司制定自己的系统接口标准，当需要执行系统整合、自定义和程序应用等操作时，公司所有成员都可以通过该接口标准调用源代码，该接口标准被称之为开放式 API。  

API设计

背景

目前互联网上充斥着大量的关于RESTful API（为方便，下文中“RESTful API ”简写为“API”）如何设计的文章，然而却没有一个”万能“的设计标准：如何鉴权？API 格式如何？你的API是否应该加入版本信息？当你开始写一个app的时候，特别是后端模型部分已经写完的时候，你不得不殚精竭虑的设计和实现自己app的public API部分。因为一旦发布，对外发布的API将会很难改变。

在给SupportedFu设计API的时候，我试图以实用的角度来解决上面提到的问题。我希望可以设计出容易使用，容易部署，并且足够灵活的API，本文因此而生。

API设计的基本要求

网上的很多关于API设计的观点都十分”学院派“，它们也许更有理论基础，但是有时却和现实世界脱轨（因此我是自由派）。所以我这篇文章的目标是从实践的角度出发，给出当前网络应用的API设计最佳实践（当然，是我认为的最佳了~），如果觉得不合适，我不会遵从标准。当然作为设计的基础，几个必须的原则还是要遵守的：

当标准合理的时候遵守标准。

API应该对程序员友好，并且在浏览器地址栏容易输入。

API应该简单，直观，容易使用的同时优雅。

API应该具有足够的灵活性来支持上层ui。

API设计权衡上述几个原则。

需要强调的是：API的就是程序员的UI，和其他UI一样，你必须仔细考虑它的用户体验！

使用RESTful URLs 和acTIon.

虽然前面我说没有一个万能的API设计标准。但确实有一个被普遍承认和遵守：RESTfu设计原则。它被Roy Felding提出（在他的”基于网络的软件架构“论文中第五章）。而REST的核心原则是将你的API拆分为逻辑上的资源。这些资源通过http被操作（GET ，POST，PUT，DELETE）。

那么我应该如何拆分出这些资源呢？

显然从API用户的角度来看，”资源“应该是个名词。即使你的内部数据模型和资源已经有了很好的对应，API设计的时候你仍然不需要把它们一对一的都暴露出来。这里的关键是隐藏内部资源，暴露必需的外部资源。

在SupportFu里，资源是 TIcket、user、group。

一旦定义好了要暴露的资源，你可以定义资源上允许的操作，以及这些操作和你的API的对应关系：

GET /TIckets # 获取TIcket列表

GET /tickets/12 # 查看某个具体的ticket

POST /tickets # 新建一个ticket

PUT /tickets/12 # 更新ticket 12.

DELETE /tickets/12 #删除ticekt 12

可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint：/tickets，再没有其他什么命名规则和url规则了，cool！

这个endpoint的单数复数

一个可以遵从的规则是：虽然看起来使用复数来描述某一个资源实例看起来别扭，但是统一所有的endpoint，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。

如何处理关联？关于如何处理资源之间的管理REST原则也有相关的描述：

GET /tickets/12/messages- Retrieves list of messages for ticket #12

GET /tickets/12/messages/5- Retrieves message #5 for ticket #12

POST /tickets/12/messages- Creates a new message in ticket #12

PUT /tickets/12/messages/5- Updates message #5 for ticket #12

PATCH /tickets/12/messages/5- Partially updates message #5 for ticket #12

DELETE /tickets/12/messages/5- Deletes message #5 for ticket #12

其中，如果这种关联和资源独立，那么我们可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息。（例如这里如果message资源是独立存在的，那么上面 GET /tickets/12/messages就会返回相应message的链接；相反的如果message不独立存在，他和ticket依附存在，则上面的API调用返回直接返回message信息）

不符合CURD的操作

对这个令人困惑的问题，下面是一些解决方法：

重构你的行为action。当你的行为不需要参数的时候，你可以把active对应到activated这个资源，（更新使用patch）。

以子资源对待。例如：github上，对一个gists加星操作：PUT /gists/：id/star 并且取消星操作：DELETE /gists/：id/star.

有时候action实在没有难以和某个资源对应上例如search。那就这么办吧。我认为API的使用者对于/search这种url也不会有太大意见的（毕竟他很容易理解）。只要注意在文档中写清楚就可以了。