怎样大规模交给高质量、高共同性的RESTful API及配套产品

摘要

近年来互联网技能开展飞速，API生态敏捷扩张，从RPC到REST，再到现在的GraphQL，不同的风格和标准，在必定程度上，确实是在让开发者更好的在项目中开发和运用API，可是在怎样交给高质量、高共同性的API（尤其是RESTful风格的API）及配套产品的方面，还没有十分实质性的推动，本文作者将会结合本身开发经历以及在云厂商的大规模敞开API的规划经历，经过对RESTful相关论文的阅览，典型的RESTful风格的API标准（Google Cloud和Github的RESTful风格的API标准）探究，以及对在多团队协同开发、交给高共同性的RESTful API所面临的困难，经过API交给流程、RESTful API的风格剖析、标准定制，东西建造等几个方面，对怎样大规模交给高质量、高共同性的RESTful API及配套产品进行剖析，一起作者将会结合在腾讯如此API团队的作业经历，并以阿里云Serverless相关API举例，对高质量、高共同性的API标准规划、API发布渠道的建造进行研讨和评论。

本文一共包含三个首要章节以及前语部分和总结部分，三个首要章节分别是：

• 第一章：什么是RESTful：本章将会经过对RESTful的论文、典型的RESTful风格的渠道（Google Cloud、Github）的研讨，经过对OpenAPI3.0、Swagger、GraphQL的进一步探究，学习和了解RESTful，以及对“怎样标准好一套RESTful风格的API”进行评论；
• 第二章：团队协同与高质量/共同性：本章将会经过团队协作与共同敞开API发布时所面临的应战，经过团队协同的风格与标准为入口，对内部团队与外部用户衔接点的建造进行探究和评论；
• 第三章：大规模交给API及配套产品处理计划：本章将会经过大规模API交给的流程、以及RESTful风格的规约、敞开RESTful风格API的标准/规划攻略，以及对内共同敞开API发布渠道建造等进行评论，并依据本身在腾讯如此API团队对Explorer，以及内部东西等项意图规划经历，以及以阿里云Serverless相关敞开API为事例，对怎样大规模交给高质量、高共同性的RESTful API及配套产品进行综合性探究；

1 前语

假如说API是模块或许子体系之间交互的接口界说，那么API规划的好坏，就会直接影响体系对接时的开发复杂度，以及之后的运维复杂度；相同，一套完善的、标准的、科学的敞开API，也会在必定程度上对用户的心智、产品的全体品牌形象，用户的信任感等会有比较大的影响。在大规模的敞开API规划和对外发布的进程中，一般会面临两个比较大的应战：

• 多团队共同保护的大规模敞开API产品，怎样做到高质量、高共同性是十分具有应战性的作业；

• 与内部API不同的是，像云产品的API，支付类产品的敞开API在对外露出时，不只仅要在功用、安稳、安全等层面付诸更多的精力，还要在标准、科学、全体性上加强建造；因为这类API一般具有以下特色：

  • 体系级的对接：一旦对外露出，就很难取消/改动，因为这很或许触及到外部用户体系的安稳性问题；
  • API数量庞大：一般触及到多个产品，所以相对来说API数量会十分庞大，乃至或许超过数千个；如此庞大的敞开API数量，其能让用户快速发现，快速了解，快速运用，快速调试就成了极具应战的作业了；
  • 高度的共同性和互通便利性：一般是由多个事务线共同保护；其风格，以及多团队间产品互通性是需求做到共同和确保的（包含不限于共同的SDK、共同的签名办法、同类的参数共同命名、风格的共同性等）；
  • 安稳性和安全性便是生命线：因为一般与用户的体系直接相关，假如呈现问题或许直接对用户的体系构成直接的影响，所以这一部分的安全性和安稳性好像生命线，十分重要，要有一个明晰的确保；

针对上述的应战和大规模云产品/支付类API的特色，在进行大规模高质量、高共同性的RESTful API交给时则需求注意以下内容：

• 对内部团队的规约：

  • 完善的敞开API规划攻略：例如基于RESTful风格的API标准等，将会包含命名标准、数据结构的标准、过错信息的标准等；
  • 科学的敞开API发布流程：API一旦对外就或许触及到体系级对接，所以难以撤回，难以更改，API发布的时分必定有完好的流程，包含不限于API的录入、预发、自测、测验、审阅、发布等流程；

• 对内部团队供给的东西/才干：

  • 完好的事务笼统才干：例如频率束缚、共同鉴权、共同容灾等上层笼统才干；
  • 共同敞开API发布东西：完好的API录入、测验、发布的内部东西链，帮忙内部团队更简略、更便利、更科学的进行敞开API发布；
  • 共同敞开API发布检查和巡检作业：供给完好的敞开API上线前巡检、测验等相关计划等；

• 对外部用户交给的产品：

  • 共同风格的文档：需求为用户供给共同的、标准的敞开API接口文档、接口改动记载、晋级计划等；
  • 共同风格的配套产品：需求为用户供给共同的SDK、API Explorer等相关的配套产品；

2 什么是RESTful

跟着互联网技能的飞速开展，尽管RESTful风格的敞开API现已成为了行业的“事实标准”，可是实践上RESTful描绘了一个架构样式的网络体系，并没有明晰的标准，正如维基百科和百度百科所说的一样：RESTful更像是一种规划风格。这种规划风格是 HTTP 标准的首要编写者之一的Roy Fielding博士在其博士论文《Architectural Styles and the Design of Network-based Software Architectures》中进行界说和描绘的。在现在主流的三种Web服务交互计划中，REST比较于SOAP（Simple Object Access protocol，简略方针拜访协议）以及XML-RPC愈加简略明了，无论是对URL的处理仍是对Payload的编码，REST都倾向于用愈加简略轻量的办法规划和完结。现在也有许多典型的，优异的RESTful风格的API接口，例如Gihub、Rapidapi、Google等。

2.1 RESTful的风格与标准

经过对Roy Fielding的博士论文《Architectural Styles and the Design of Network-based Software Architectures》阅览与剖析，尤其是其第五章关于RESTful的部分学习，能够看到这篇论文仅仅是对RESTful进行了一些风格的束缚，并没有进行标准拟定。所以无论是在百度百科中，仍是在维基百科中，RESTful的相关词条都是被十分明晰的阐明：RESTful是一种风格，而非一种标准。

在Roy Fielding的博士论文第五章（表述性状况转移（REST））中，Roy Fielding以为REST供给了一组架构束缚，当作为一个全体来运用时，着重组件交互的可伸缩性、接口的通用性、组件的独立布置、以及用来削减交互推迟、增强安全性、封装留传体系的中心组件，一起这组架构束缚也被总结成了六个中心部分：

• 客户端-服务器
• 无状况
• 可缓存
• 分层体系
• 按需代码（可选）
• 共同的接口

2.1.1 常见的RESTful风格标准

尽管RESTful风格被更多人所承受，也被更多人运用到本身的事务中，可是因为RESTful更多来说并不是一个标准，因为他没有对API的具体表现形状进行强束缚，地点实践出产中“高质量、高共同性”的RESTful风格API难以落地。此刻与RESTful配套的敞开API标准/规划攻略，就显得尤为重要，现在来看大多数开发者，关于RESTful风格的普遍认知包含以下部分：

• URI标准

  • 不必大写，共同小写；
  • 用中杠（ - ）代替下划线（ _ ） ；
  • URI中的词汇要用名词，尽量不要用动词；
  • 名词表明资源调集，运用复数方式；
  • 在URL中表达层级，用于按实体相相联系进行方针导航 ，一般依据id导航；

• 版别

  • URL中表达出API与版别，例如：

    • api.example.com/v1/
    • www.example.com/api/v1/

• 恳求

  • GET：安全且幂等，获取表明；
  • POST：不安全且不幂等，运用服务端办理的（主动发生）的实例号创立资源、创立子资源、部分更新资源，假如没有被修正，则不更新资源（达观锁）；
  • PUT：不安全但幂等，用客户端办理的实例号创立一个资源，经过替换的办法更新资源，假如未被修正，则更新资源（达观锁）；
  • DELETE：不安全但幂等，删除资源；
  • PATCH：在服务器更新资源（客户端供给改动的特点）；

• 状况码

  • 运用状况码表明服务状况，常见规约有（仅举例阐明）：

    • 200 （OK）：假如已存在资源被更改；
    • 404 （not found）：资源不存在；
    • 503 （Service Unavailable）： 服务当时无法处理恳求；

• 服务器回应

  • 不要回来纯本文，应该是一个 JSON 方针，因为这样才干回来标准的结构化数据；
  • 发生过错时，不要回来 200 状况码，有一种不恰当的做法是，即便发生过错，也回来200状况码，把过错信息放在数据体里边；
  • 供给链接，API 的运用者未必知道，URL 是怎样规划的。一个处理办法便是，在回应中，给出相关链接，便于下一步操作。这样的话，用户只需记住一个 URL，就能够发现其他的 URL；

2.1.2 OpenAPI3.0与Swagger

当提到RESTful风格的敞开API标准，就不得提及OpenAPI3.0和Swagger。在OpenAPI3.0的官方Repo中，咱们能够看到这样的描绘：

The OpenAPI Specification is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.

this specification is not intended to cover every possible style of HTTP APIs, but does include support for REST APIs.

所以，咱们是能够以为RESTful是一种风格，OpenAPI 3.0是他的最新标准，而Swagger是这个标准配套的相关东西。

OpenAPI 标准（OAS）界说了一个标准的、语言无关的 RESTful API 接口标准，它能够一起答应开发人员和操作体系检查并了解某个服务的功用，而无需拜访源代码，文档或网络流量检查（既便利人类学习和阅览，也便利机器阅览）。正确界说 OAS 后，开发者能够运用最少的完结逻辑来了解长途服务并与之交互。

在标准中，能够看到对许多内容进行了明晰阐明和界说，例如：

• 关于OpenAPI的版别：敞开API标准运用符合语义化版别 2.0.0(semver)标准的版别号；
• 格局：一份遵照敞开API标准的文档是一个自包含的JSON方针，能够运用JSON或YAML格局编写；
• 文档结构：一份 OpenAPI 文档能够是单个文件也能够被拆分为多个文件， 衔接的部分由用户自行决定；
• 数据类型：在 OAS 中的原始数据类型是基于 JSON Schema Specification Wright Draft 00 所支撑的类型；
• 富文本格局：整个标准中的 description 字段被标记为支撑 CommonMark markdown 格局；
• URL的相对引证：除非明晰指定，一切 URL 类型的特点值都能够是相对地址，就如 RFC3986 中界说的那样以 Server Object 作为 Base URI；

除此之外还对结构，以及结构中的方针（例如Server、Paths等）进行了比较具体标准和界说。

2.1.3 小结

当咱们仔细读完Roy Fielding的博士论文《Architectural Styles and the Design of Network-based Software Architectures》之后，咱们会逐步的发现，RESTful更多时分并非标准、也并非技能、服务、组件，而是一种风格，隐藏在RESTful背面的理念便是运用Web的现有特征和才干， 更好地运用现有Web标准中的一些准则和束缚。

正如他在论文中所说的："我这篇文章的写作意图，便是想在符合架构原理的条件下，了解和评价以网络为根底的运用软件的架构规划，得到一个功用强、功用好、适宜通讯的架构。REST指的是一组架构束缚条件和准则。假如一个架构符合REST的束缚条件和准则，咱们就称它为RESTful架构。”

跟着时刻的开展，RESTful逐步的在风格之上发生了一些标准，有通用性的标准，普适性的标准，也有不同的安排，不同的厂商依据本身的事务诉求等定制的标准，可是无论怎样咱们能够肯定的是：想要具有RESTful风格，就必需求有一套完好的标准。尤其是在多团队协同开发，具有许多接口的条件下，这个标准显着更为重要，假如把RESTful和标准比方人类社会，我更觉得RESTful是品德本质，OpenAPI等是法令规矩；在本质良莠不齐的时分，就要靠法令进行终究的规约。

2.2 典型的API渠道/生态与RESTful探究

现在在运用RESTful风格的网站或许渠道是十分多的。例如十分典型的包含：

• Github某repo的issue：https://github.com/OAI/OpenAPI-Specification/issues/2674
• 阿里云函数核算的操控台：https://fc.console.aliyun.com/fc/service/cn-hangzhou/anycodes-tiku/function/server/overview
• 知乎的问题与答案：https://www.zhihu.com/question/24795126/answer/41691845

除了这些十分经典的网站在选用RESTful风格，许多个人的网站项目，也在选用RESTful风格，例如：

• 我的个人博客，某个标签下的文章列表：http://bluo.cn/tags/cold-start
• 我的一个小程序获取某题意图评论内容：https://server.anycodes-tiku.1583208943291465.cn-hangzhou.fc.devsapp.net/api/v1/comments/questions/{问题id}

当然，一些开源结构本身也是默许是RESTful风格的，例如：

• Python Web结构中的Django结构，后台进行文章处理时：https://www.example.com/admin/article/articlemodel/3/change/

经过上面举例的这些典型的RESTful风格的网站，咱们不难发现一件作业：他们看似共同，却又不同。例如：

• 在Github某repo的issue与知乎的问题/答案部分，能够看到前者的issue是复数，后者的question和answer是单数；
• 在Python Web结构，Django结构的后台更新文章的部分，能够看到其包含了一个动词change；

此刻不难发现一件事，无论是个人所规划的RESTful风格API仍是一些经典RESTful API事例，其都是在RESTful束缚的根底上，进行了部分自界说的标准，而且这种自界说的标准往往是与本身事务高度契合的，即会依据本身事务特性进行必定的标准定制。

2.2.1.Github事例

提到RESTful风格的API，就不得不说GIthub，关于咱们现在所看到的Github而言，无论是网站的途径仍是敞开的API，都能够以为是十分标准的RESTful风格，乃至能够以为其近乎悉数接口都遵从了OpenAPI的标准，这一点在Github的文档中也能够得到印证：

OpenAPI 是描绘 REST API 的标准标准。 OpenAPI 描绘答应人类和核算机无需首要阅览文档或了解完结完结即可发现 API 的功用。 GitHub 现已以 OpenAPI 3.0 标准文档的方式公开其 REST API。

在Github的REST API中，能够十分明晰的感受到在REST中的一切都被以为是一种资：当看到Github的任何一个地址，或许任何一个敞开API，都能够让用户会很直观了解到其对应的资源，或许这便是REST风格十分重要的价值。

在Github的RESTful API中，咱们能够看到其经过资源、媒体类型等几个层面，借用OpenAPI 3.0的标准，有针对性的对本身的敞开API作出了较为严厉的标准。经过对该文档的仔细阅览，不难发现其优点是十分显着的：

• 对资源的隶属分类处理的十分好，能够使开发者直观的明白和了解；
• 对各种接口的变迁有方针的描绘，也有对应的处理计划；
• 充沛的运用了恳求头，例如能够经过http的Accept头部字段进行拟定运用其他的数据格局(不是json)的接口；
• 对一些过错码的处理愈加详尽，例如未授权的状况下拜访私有资源，并不是401（Unauthorized）而是404（not found），这样做的好处是为了不让进犯者容易找到内部的资源（依照严厉意义上来说，这个并不是十分归于“普适性RESTful”的标准，这个算是定制化的标准计划，可是十分有意义）；

2.2.2.Google Cloud事例

假如说Github的RESTful风格API标准，是在OpenAPI 3.0根底上进行进一步定制和完善，是借用已有标准快速构本钱身标准的办法，那么Google Cloud的敞开API标准，则是一种极具创造性的将本身的gRPC与RESTful进行了有机结合，诞生了独具匠心，却又十分经典的敞开API规划攻略。

这篇规划攻略中，十分明晰的界说了面向资源的规划概念。一起也直接表明了这份规划文档是Google Cloud依据一些状况，定制化的一个规划攻略，即满意RESTful的标准，可是实践上是自己界说的标准：

RPC API 一般依据接口和办法规划。跟着时刻的推移，接口和办法越来越多，终究成果或许是构成一个庞大而混乱的 API 接口，因为开发者有必要独自学习每种办法。显着，这既耗时又容易犯错。引进 REST 架构风格首要是为了与 HTTP/1.1 配合运用，但也有助于处理这个问题。 HTTP REST API 在互联网上取得了巨大成功。2010 年，大约 74% 的公共网络 API 是 HTTP REST（或相似 REST）的 API，大多数 API 均运用 JSON 作为传输格局。尽管 HTTP/JSON API 在互联网上十分流行，但它们承载的流量比传统的 RPC API 要小。例如，美国顶峰时段大约一半的互联网流量是视频内容，显着出于功用考虑，很少有人会运用 HTTP/JSON API 来传送此类内容。在数据中心内，许多公司运用基于套接字的 RPC API 来承载大多数网络流量，这或许触及比公共 HTTP/JSON API 高几个数量级的数据（以字节为单位）。

之所以说Google Cloud的这份敞开API规划攻略独具匠心，却又十分经典，是因为在这份攻略中，不只能够看到典型的RESTful风格敞开API标准的具体规划计划，更能够明晰地看到为什么这个规划，这么规划的价值是什么，能够以为这份API实践攻略十分具有学习性和研讨价值。

在这份规划攻略中，能够看到Google在敞开API规划进程中的一些重视点：

• 其中心准则是界说能够用少数办法操控的命名资源。这些资源和办法被称为 API 的“名词”和“动词”；
• 运用 HTTP 协议时，资源称号天然映射到网址，办法天然映射到 HTTP 的 POST、GET、PUT、PATCH 和 DELETE；
• 一个调集包含相同类型的资源列表；
• 资源具有一些状况和零个或多个子资源。 每个子资源能够是一个简略资源或一个调集资源；
• ......

在该攻略中，也十分清楚的描绘了在规划面向资源的 API 时应该采纳的步骤：

• 确认 API 供给的资源类型；
• 确认资源之间的联系；
• 依据类型和联系确认资源称号计划；
• 确认资源架构；
• 将最小的办法集附加到资源；

除此之外，这份规划攻略还对部分规矩进行了界说，例如一些命名规矩等。以命名规矩为例，能够看到Google Cloud在界说这份规矩时的考量：

• 要有共同的方针：简略、直观、共同;

• 要针对方针有必定的标准：

  • 防止称号过载，运用不同的称号命名不同的概念；
  • 为了简化命名，能够运用已被广泛承受的简写方式或缩写。例如，API 优于 Application Programming Interface；
  • 除字段称号和枚举值外，.proto 文件中的一切界说都有必要运用由 Google Java 样式界说的UpperCamelCase格局的称号；
  • .....
• 要针对特别状况，考虑到开发者的本质问题等：因为许多开发者不是以英语为母语，所以这些命名惯例的方针之一是确保大多数开发者能够轻松了解 API。关于办法和资源，咱们鼓舞运用简略、共同和少数的词汇来命名;

有方针，有标准，有事例，有人道主义，Google Cloud的这份敞开API文档的规划攻略，可谓是许多开发者规划API时的一个重要参阅，也能够称得上是RESTful风格下的敞开API规划文档经典事例。

2.2.3.小结

尽管现在现已有一些普适性的RESTful风格的敞开API标准，也有一些安排推动建造RESTful风格标准标准（例如OpenAPI 3.0等），可是在实践出产中，若想大规模交给高质量、高共同性的RESTful风格API，仍是十分有必要拟定一套针对事务本身的RESTful风格标准；无论是和Github计划相似，在OpenAPI 3.0根底上进行部分的“晋级”；仍是Google Cloud的“自成一派”，依据本身需求，将gRPC与RESTful有机结合；相似这种的RESTful风格的敞开API标准总是要有的。

假如说RESTful风格更多是对开发者或许开发团队的一种品德本质，那么在这个风格之上拟定的标准才是真正的法令，只有咱们都有品德本质，又有法令作为支撑的条件，才干确保高质量、高共同性的RESTful风格API交给。

2.3.RESTful和GraphQL

即便RESTful风格现已得到了大规模的运用，并逐步成为Web API的事实上的标准，可是其依然是不完美的，存在着巨大的应战：

• 多端 (屡次数据交互)：例如，当获取一个文章的时分，或许要先后恳求：GET /posts/和GET /posts//comments等多个接口；
• 过度获取数据：例如客户端现已具有某些数据，只需求获取部分内容时，恳求后端之后依然是拿到了预订的悉数数据，存在过度获取的问题；
• API版别操控：API进行版别晋级时，或许会带来巨大的迁移本钱，不行控的保护风险；
• 弱类型：许多内容经过URL传递之后或许类型发生变化，不容易指定特定的数据类型，对后端的处理或许存在必定的风险；
• 客户端对数据结构的掌握不行控：在恳求某个接口之前，客户端没办法规约或许明晰其回来的数据结构，这就导致过度依靠文档的具体程度；
• 关于一些标准难以适配：例如有的标准表明RESTful风格在url中不答应呈现动词，可是在实践出产中，特别状况一旦呈现，就会发生比较难以抉择的现象；

为了战胜 RESTful风格和OpenAPI标准的相关缺点，Facebook提出了GraphQL的标准。众所周知QL是一种查询（ Query Language），所以GraphQL更多时分指的是Web API 的查询语言。相比照RESTful而言，GraphQL具有的优势也是十分显着的：

• 一次恳求获取到一切：一般状况下，GraphQL 服务只需求露出一个端点让客户端能传输必要的查询语句即可满意全体的数据获取/查询需求；
• 客户端驱动：GraphQL 供给了一种声明式语法，以便客户端准确地指定它们所需的字段。 这消除了因为客户端依据方式向 GraphQL 服务器声明其数据需求而导致数据冗余和不充沛的或许性；
• API版别操控：因为在 GraphQL 中一切都是方式（schema）驱动, 新增字段不会影响现存字段，而且 GraphQL 还为抛弃字段供给 @deprecated 注释，所以对 GraphQL 的扩展并不是问题。 这就消除了 API 版别操控的需求；
• 强类型：与RESTful不同的是，GraphQL是能够明晰出数据类型的，或许强行规约清楚数据类型；
• 传输层不行知：这是 GraphQL 的一个十分棒的优点。 API 服务器能够经过相似 HTTP, HTTPS, WebSockets, TCP, UDP 等协议进行信息交流。 这是因为 GraphQL 甚少关怀信息怎样在客户端与服务器之间进行交流；

当然就现在来看GraphQL也并不是完美的，他也有一些缺点：

• 缓存功用不老练：不支撑浏览器和移动手机缓存，这一点区别于运用本地 HTTP 缓存机制的 RESTful 服务；
• 查验与过错报告：RESTful 服务运用 HTTP 状况代码来处理或许遇到的不同过错。对开发人员来说，这使得 APIs 的查验变得十分简略和轻松，可是运用 GraphQL 服务总是回来 200 OK 呼应；
• 露出方式和资源进犯: 和RESTful服务不同，GraphQL服务要求客户端有必要知道要查询的数据方式；假如您将API露出给第三方，则根本上露出了您的内部数据结构； 有必要十分小心，因为客户端不必很高的代价就能够主张衔接查询，这或许会导致服务器上的拒绝服务（DoS）进犯；
• 安全 - 身份验证和授权：GraphQL社区依然对怎样处理GraphQL服务的安悉数分感到困惑；
• N + 1 次查询问题：在RESTful服务中，很容易记载履行的SQL查询并进一步优化它，但在GraphQL的状况下，解析性质是动态的，因此很难获得准确的查询并进一步优化它；

尽管GraphQL也并不完美，可是这并不影响其逐步被更多人、渠道、厂商所运用，例如Github现在就现已在v4版别的API上全面支撑了GraphQL。当然，也是因为RESTful风格与GraphQL在必定程度上存在互补联系，所以在许多敞开API确认形状时，都会评论要用那种计划/标准/风格。其实站在个人视点：

• 以RESTful风格的计划进行推动；
• 在后期假如GraphQL逐步更老练，而且逐步处理了安全、露出方式和资源进犯等问题之后，能够像Github一样，一起支撑两种计划/标准/风格；

2.4.怎样标准好一套RESTful风格的API

在准备界说RESTful风格的敞开API标准之前，除了要了解RESTful的典型事例是怎样进行规约的之外，还要对本身的事务有比较深化的了解，并依据本身的事务实践状况做一些特别化的处理，例如Google Cloud的API，依据网络需求将RESTful风格禺gRPC的某些标准进行交融；Github从安全的视点动身，规矩了未授权检查某些Repo作用等于资源不存在。

在进行RESTful风格的敞开API标准定制时，能够充沛参阅Google Cloud的敞开API规划攻略，经过资源相关的界说、办法相关的界说、对字段进行标准化、对过错进行界说，以及对通用才干的笼统、安全和权限等标准进行界说等几个方面进行进行具体的界说。一起要遵从以下几个准则：

• 标准定制意图：帮助开发者规划简略、共同且易用的网络 API；

• 标准定制准则：

  • 标准文档应该是考虑全面的，描绘精准无二义性的（要运用要求等级要害字（“有必要”、“不得”、“必需”，“应”、“不应”、“应该”、“不应该”、“主张”、“能够”和“可选”），并按 RFC 2119 中的描绘进行解说）；
  • 应该以RESTful风格的六个束缚作为根底准则，应该以普适性的标准或许OpenAPI 3.0标准作为参阅或许根底，不应该大规模推翻已有的认知，能够恰当的依据事务需求规划特定的标准模型；
  • 该标准文档应该具有必定的可拓展性，跟着时刻的推移，要采纳和批准新的风格和规划方式，为标准文档添加相关内容。本着这种精神，要不断完善标准文档，并为 API 规划的艺术和技巧供给足够的空间；
  • 标准文档在定制时，要充沛考虑到开发者本质以及不同人对事务了解的差异性，在不影响标准全体表达的条件下，确保高质量，高共同性的条件下，要供给必定的容错性计划，即便是容错性计划，也要供给完好的规矩，例如命名规矩，表达规矩，结构规矩等；

• 标准的普适性：

  • 首要意图是要对内部协同开发团队的开发者，进行敞开API开发和露出进行规约，确保敞开API的共同性，标准性；
  • 其次要对外进行露出，让敞开API的运用者，能够充沛了解这套敞开API的规划意图、理念、标准；
  • 终究要构成有影响力的，具有普适性的，典型的RESTful风格的敞开API标准，例如Google Cloud的敞开API规划攻略就能够称之为是该领域内的最佳实践，具有必定的参阅性和学习性，相同也极具有影响力；

3 团队协同与高质量/高共同性

当一个项目或许一个产品决定对外敞开API时，一般会遇到一个十分具有应战的问题：怎样确保对外敞开的API的质量和共同性？这样的应战在云厂商中尤为巨大，无论是腾讯云仍是阿里云，在对外露出高质量、高共同性的API时，都面临着十分严峻的质量问题、共同性问题，乃至云厂商一度将一切的敞开API对外露出的出口，共同收敛到同一个团队，进行强规约、强束缚，例如腾讯如此API团队，阿里云的POP团队等。

那么在团队协作的条件下，对外发布敞开API的进程中，怎样确保敞开API的高质量、高共同性呢？经过一套完好的标准就能够处理这个问题么？腾讯云、阿里云为何要在有共同的标准条件下还要收敛到一个团队作为共同出口？除了风格的明晰、流程的明晰，标准的完善，是否还要有配套的东西帮忙高质量、高共同性的API对外发布？

3.1 团队协同与API生态的抵触与交融

一个产品/项目由多个团队共同协作完结是十分正常的作业，可是往往这种协作带来的是一种敞开API生态的“不交融”。这其中的原因有许多：

• 不同成员对事务的了解是不同的；
• 不同团队所负责的事务功用是不同的，从而不同团队的重视点是不同步的；
• 不同的开发者本质是不同的（包含作业的情绪、英文的水平以及个人的性情等）；

以作者在某云做云 API产品司理是的实在作业为例：不同的云产品都有获取实例的接口，可是即便相同是获取实例，在不同的团队中对其的感觉和界说是不同的；团队A界说的行为是GetInstance，团队B则界说成了DescribeInstance，从不同的人的视点去了解其实这两者都是能够的，没有谁对谁错的说法，可是假如在作为一个云API团队，共同露出出API的条件下，呈现两种方式的表达，则是不合理的，更何况在云厂商中，不同的产品都有获取实例的接口，那么抛弃掉刚刚所说的GetInstance和DescribeInstance，是不是还有或许呈现InstanceInformation、ObtainInstance等更多的形状？假如一个开发者在运用云产品的敞开API时，不同的产品同一个接口的行为表现彻底不同，岂不是会让开发者觉得该云厂商很不专业，内容很乱，很随意；从而损失对产品的信任。相同的作业，也能够在Github的API中进行研讨和思考：

• 什么时分用edit，什么时分用update；
• 什么时分用delete，什么时分用remove；

从上面的实在事例，咱们能够发现团队协作是必定，协作后的产品，尤其是对外敞开的API产品，怎样坚持高度的共同性，在没有绝对的收口之前，这将会是“协作”与“共同”的巨大抵触，所以怎样处理这个抵触，就成了大部分跨团队协作对外敞开API的产品/项目，所面临的巨大应战。

无论是在阿里云的POP团队，仍是在腾讯如此API团队，在处理这个抵触的作业时，都选用了软硬兼施的计划，所以为的“软”是说要潜意识的培养和标准的明晰；所谓的“硬”是说要有强制收口的共同发布渠道，确保终究发布时的共同、兼容性、安全性以及高质量。以RESTful风格的敞开API为例，需求有三个层面的要求：

• 潜意识：要运用RESTful风格界说API
• 标准层面：需求有一个十分明晰的规划攻略，这份规划攻略不只对内，相同要对外；而且这份攻略不能有二义性；
• 强制收口：所谓的强制收口是咱们对外露出API的终究一道防地，这一道防地需求进行人工审阅，要确保全体的共同性就必定要尽或许的收敛到一个部分进行共同审阅；

综上所示，想要处理抵触，弱化应战，让团队协同与高质量/高共同性不再抵触，有机交融，那就要经过上述的潜意识、强标准以及强制收口三个方面进行探究。

3.2 团队协同的风格与标准

所谓的团队协同的风格与标准是在规划敞开API前和进程中所需求重视的。

3.2.1 风格明晰

在API准备开发/晋级之前，首要需求明晰对外露出的敞开API风格，例如RESTful，GraphQL，或许是其他的标准/标准，例如RPC等。尽管敞开API的规划攻略在必定程度上要坚持活性，不断的兼容更新的标准等（例如Github的敞开API在v3版别支撑RESTful风格，在v4版别支撑GraphQL标准），可是仍是要在规划之初，明晰当时版别的风格，本文将会以RESTful风格为首要探究的方向，在未来假如GraphQL进行了更快速的开展和迭代，用户的诉求逐步强烈，能够和Github蕾丝，一起考虑RESTful风格GraphQL的计划。

3.2.2 标准定制

标准的拟定是在风格确认之后，以RESTful风格为例，需求拟定资源相关、办法相关、字段进行标准化、过错等若干层面的标准。

3.2.2.1 资源相关的界说

因为RESTful在必定程度上是面向资源的，所以需求在标准拟守时明晰资源具体状况：资源的品种、联系；资源的上层笼统，多产品/事务下同类资源的共同；自界说资源的界说标准；具体表述如下：

• 资源内容整理：尤其是不同团队的表述或许共同的资源，例如以云产品为例，在云主机处或许经过将某个机器的id界说为instanceId，在数据库处或许某个数据会被界说成resourceId，此刻就需求评价这两个是否表明同类内容，都是资源或许实例的id，假如能够确认是同类内容，那就要在上层规约好他们的资源名，例如就叫做instance或许resource等，防止同类概念呈现在不同的接口中，表述是不同的问题呈现；
• 资源隶属联系的确认：依照道理从左到右应该是调集逐步包含资源，所以在进行资源界说的时分要明晰清楚资源的隶属联系，防止呈现A检查的x模块包含了y模块，而B则是y模块包含了x模块这种产品间的包含联系抵触，例如某产品界说是服务下包含了项目，而另一个产品时项目下包含了服务，此刻就要进行概念的交融和调整，以完结对外的共同性表述；
• 资源命名标准：指的是是否能够运用动词，什么时分运用动词，链接符用什么，每个资源命名最长是多少；例如检查某个核算机类目下的一切图书能够表明为//api.example.com/v1/category/computer/books；
• 资源表达标准：是运用某个资源称号，仍是运用资源id；例如1.1中运用资源称号的比如也能够用资源id这样表达：//api.example.com/v1/category/1/books，可是什么时分用id，什么时分用称号，这个是需求规约清楚的；
• 某些参数的确认：事务不或许彻底经过URI进行一切的功用确认，例如查询操作，就或许会被规划为//api.example.com/v1/search?query={要害词}，此刻也需求对一些通用参数进行规约；除此之外某些恳求办法（例如POST）等，也或许需求对某些数据结构进行明晰和标准；
• 对自界说内容进行明晰：尽或许多的供给一些示例或许事例，可是往往在标准的时分也会呈现一些极特别的状况，所以此刻还需求对一些事务团队可自界说的内容进行额定的约好。例如Google Cloud中所描绘的状况： 因为许多开发者不是以英语为母语，所以这些命名惯例的方针之一是确保大多数开发者能够轻松了解 API。关于办法和资源，咱们鼓舞运用简略、共同和少数的词汇来命名；

3.2.2.2 办法相关的界说

除了对资源相关内容进行明晰的界说，还需求对一些通用办法进行笼统，以及部分自界说办法进行约好，一起还要将相关的办法映射到HTTP的办法上：

• 规约中心的办法：在拟定标准时，需求规矩好一切团队能够运用的通用办法，例如List、Get、Create、Delete、Start、Restart、Stop、Update等办法；一起要明晰这些办法与HTTP的映射联系，例如标准办法List和Get映射到HTTP的办法是Get，Create映射到HTTP的办法是POST等；

• 规约自界说办法：即便咱们规约了许多的中心办法之后，笼统出来了许多通用办法之后，在实践出产中，因为各个团队处理的事务是复杂的，所以还会呈现一些自界说办法，此刻的处理办法有两种：

  • 相似于Google Cloud的处理办法：即在URL中直接表现：https://service.name/v1/some/resource/name:customVerb；
  • 将指定的办法放到Header中：例如在Header中指定Action: customVerb；

3.2.2.3 对字段进行标准化

这一部分包含了笼统的事务字段以及自由字段，一起还要明晰规矩自定界说的标准：

• 规约标准化字段：此刻能够经过一些笼统的名词标准化一些字段，例如创立实体的时刻能够固定为create_time ，这一部分和资源相关的界说中的资源内容整理部分有些相似，可是前者更注重于资源，而这儿对字段标准化时则不只仅是资源，也包含时刻、状况等；

• 规约自界说字段标准：针对一些无法笼统的字段，能够选用三段式进行标准：

  • 尽量选用供给的标准字段;
  • 标准字段无法满意时，能够选用所供给的独立字段进行组合，例如供给describe和information字段，组合成describe_information;
  • 标准字段无法满意时，能够进行自界说字段，可是要遵从必定的规矩（此处规矩能够尽或许的具体，例如只能是名词，链接符用下划线等）；

3.2.2.4 对过错进行界说

除了上述所述内容之外，标准中还需求对过错的状况进行界说，以及对过错的结构，过错码进行界说：

• 体系过错：需求对体系级过错进行共同和标准，所谓的体系级过错指的是因为不行控因素导致一些问题的呈现，例如后端事务无呼应，此刻渠道侧进行指定的过错码和过错结构回来；
• 事务过错：因事务本身导致的一些过错，例如用户传递的参数过错、不存在等；此刻需求笼统出部分过错码（必要时能够供给一级过错码和二级过错码，例如INVALID_ARGUMENT能够添加二级过错码ARGUMENT_TYPE_ERROR、 ARGUMENT_NAME_ERROR等；）；
• 自界说过错：自界说过错是指在极特别状况下，体系过错和事务过错无法覆盖的场景，能够支撑事务团队自界说过错码，可是这种过错需求依照必定的标准进行拟定；
• 过错结构/组成：尽管说会笼统出一些过错码，例如Google Cloud规约的过错结构如下：

{ "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "status": "INVALID_ARGUMENT", "details": [
      { "reason": "API_KEY_INVALID", "domain": "example.com", "metadata": { "service": "translate.example.com" }
      }
    ]
  }
}

此刻，能够依据实践事务需求规约好制化的过错信息。

3.2.2.5 其他的界说

• 相应内容的界说：在一些呼应头，Body中，也需求界说好固定的结构或许标准，例如RequestId的位置；长期实践运行无法快速得到成果的恳求，回来体构成；
• 通用才干的笼统：例如分页才干、排序才干、筛选才干是否需求作为上层笼统才干共同界说；
• 权限与安全的界说：例如越权检查某些资源是回来401仍是回来404（例如Github在匿名拜访私有Repo就会提示404，这在必定程度上是为了防进犯，放数据猜想，数据泄露）；
• 其他：其他号包含频率、包含缓存战略、包含Etag等；

3.3 内部团队与外部用户的衔接点建造

假如说API风格的明晰和规划攻略的完结是API开发之前要做的作业，一起API开发进程重要遵从相关的标准。那么API对外发布渠道则是API开发之后，上线之前的一个十分重要的要害点，这个要害点也能够以为是内部团队与外部用户的中心衔接点，经过这个衔接点，将会正式对外大规模露出高质量、高共同性的RESTful风格的敞开API以及配套产品。所以这个链接点的重要性可想而知，一般状况下，该API对外发布渠道包含的内容有：

• API录入：这一部分包含了API根底信息的入库，以及上层的笼统才干，例如共同的鉴权规矩、针对不同事务笼统的超频束缚，容灾战略等；
• API的测验/体会：该部分包含了API上线之前的自测、预发布测验以及上线后的状况预览，以便开发团队和API渠道愈加明晰、直观的确认出API的终究对外交给的形状；当然，这儿也包含配套产品的预览，例如文档、SDK、API Explorer等；
• API风格、标准的复审：这一部分是API团队需求在该渠道上进行的操作，首要要确保API的风格共同、兼容性以及标准的正确运用等；
• API终究确认与发布：当一切都确认完结之后，该渠道要供给完好的对外发布确认逻辑以及对外共同发布的才干；

• API配套资源的主动发布：这一部分首要是API对外发布之后，还需求有相关的配套才干标准化出产与上线：

  • API文档
  • 对应多语言的SDK
  • 对应的沙箱环境等
  • API Explorer的更新
  • 对应的资源聚合页的更新（例如过错中心等，API中心等）

综上所述，该渠道既然承载了敞开API共同收口的，对外露出的要害作业，那么该渠道存在的价值不言而喻：

• 对内：

  • 确认API的全体质量，共同性
  • 对内供给API层面的标准、保护计划、发布东西、测验验证渠道
  • 收敛全体问题的终究一道防地

• 对外：

  • 交给共同的心智
  • 交给科学标准的心智
  • 交给配套的设施（例如文档、SDK等）

4 大规模交给API及配套产品处理计划

在多团队协作的条件下，怎样大规模交给高质量、高共同性的RESTful API及配套产品是一个十分具有应战性的作业。正如前文所说的，在某些条件下，团队协作是必定，可是这种必定会和对外露出“共同性”的敞开API发生巨大的抵触，所以怎样大规模交给，一起又能坚持共同性，下降抵触带来的负面影响，就需求有明晰的敞开API风格、完好的API发布流程、明晰的敞开API规划攻略以及相对应的东西/渠道：

如图所示，在多个开发团队，决定要共同对外发布敞开API时：

• 首要就要明晰风格和标准，例如选用RESTful风格，选用OpenAPI标准，并依据本身特性进行部分定制化；
• 当完结API开发之后，就需求走共同的API发布渠道，进行API的录入、调试、测验等；
• 完结一系列流程之后，共同的API发布渠道必定要有人工审阅，审阅经过才干进行正式的对外发布；
• 发布完结由共同的东西进行API文档、SDK、API Explorer等产品的更新晋级；一起要在社区生态进行同步的更新以及告知；

整个流程的中心在于：共同的收口。其根本思路是：不再单纯依托风格作为品德束缚，也要有标准作为法令束缚，更要有东西作为法令的履行，只有三者协作，才干确保“社会的和谐与问题”，即API生态的标准、共同、科学。

4.1 流程、风格、标准、东西的协同建造

若想大规模交给高质量，高共同性的RESTful风格的敞开API，必定要从流程、风格、标准和东西四个视点进行建造。

就现在状况来看，典型的大规模交给高质量，高共同性的API渠道非各云厂商莫属，无论是阿里云的POP网关团队仍是腾讯云的云API团队，其中心的做法都是：

• 有完好的API发布流程，发布露出共同收口到一个团队；
• 有明晰的风格影响用户的和开发者的心智；
• 有明晰的标准接口的称号、参数、过错、恳求/呼应进行束缚；
• 有完善的API发布渠道，做共同的录入、测验、预发、发布等，以及共同对外供给配套服务；

所以本章将会从流程是整个API从零到一的生命线、风格是是API的气质，是品德束缚、标准是法令条款，是一种强束缚、东西是履行规矩，是终究收口与共同性的确保等四个方面进行具体的探究，并以阿里云Serverless相关的API为例，对API标准的定制进行更深化的举例。

4.1.1 流程是API从零到一的生命线

在项目开端之前，首要要让一切人知晓敞开API发布的完好流程，只有这个进程十分明晰明晰，才有助于后续作业的展开：

如上图所示，整个流程分为两个大类别团队以及三个中心流程：

• 团队：

  • API团队：即终究对一些才干，功用收口的团队；例如腾讯如此API团队，阿里云POP网关团队；
  • 事务团队：事务才干开发的团队，具体的功用供给者；

• 流程：

  • 开发前：首要是一些规矩、标准的明晰，有主有后续开发的和发布；
  • 开发中：首要是接口的开发；
  • API发布：首要是高质量、高共同性的发布；

4.1.1.1 开发前明晰职责，了解流程

开发前首要要做的作业是，API团队要明晰API的发布流程，以及敞开API的风格，而且输出API的标准/规划攻略，这三个内容十分重要。一起，还需求和事务团队坚持沟通，例如一个共同的群进行信息的动态更新（例如发布了某个特性，新版别发布等），并让事务团队清楚咱们的风格、标准以及流程。

这儿需求额定注意，开发前要明晰API发布的周期，以及特别状况下API紧迫上线的流程。例如：

• 规矩每周四晚上11点进行API发布，假如第二天歇息，则向前推动一天；
• 假如发布的API存在危险或许问题，需求团队相关负责人主张紧迫API发布恳求，由API网关团队的相关同学快速呼应，赶快发布；
• 在非紧迫状况下不行走紧迫发布，紧迫发布之后需提交紧迫发布的复盘，例如为什么呈现紧迫发布，具体呈现问题的进程，有什么办法能够规避等；

开发前就要尽或许做到咱们思路共同，问题最小化。

4.1.1.2 开发中了解风格，遵从标准，

• 开发之初，推荐先即将开发的API预录到体系中，并由API网关团队的同学进行API的初审，在这个时分能够对一些风格、标准等进行开始的确认，尽或许的提早露出一些问题，以便与API的开发更快速，过错率更低；
• 在API开发的进程中，要以RESTful风格的API为中心根底，严厉遵守敞开API的规划攻略进行API的参数规划、过错规划以及资源界说、行为界说等；

4.1.1.3 API发布流程严厉，对外标准化

• 完结API开发之后，需求再次确认预录信息的准确性，假如有部分内容发生了改动，要及时在体系中进行更新；
• 由API网关团队同学再次审阅确认之后才能够进行之后的发布流程；
• API事务团队需求在测验环境对API进行调试、完结之后发布到预发环境，再次进行测验，确认无误，能够提交到API的正式发布；

• API网关团队的同学需求对要发布的API进行检查，包含：

  • 标准性的检查；
  • 兼容性的检查；
  • 测验成果的检查；
• 完结上面一切流程之后，API网关团队的同学能够正式对外发布API（在发布之前需求和事务团队再次确认发布时刻）；

• API发布完结的一起，要进行相关配套服务的更新，包含不限于：

  • API Explorer
  • SDK
  • API文档
  • 相关的聚合页面
• 终究在生态和相关社群，进行相关信息的告知，以及changelog的更新等；

4.1.2 风格是API的气质，是品德束缚

当现已存在了完好的，明晰的API开发发布流程之后，还需求对API的风格进行界说。对API风格选用的架构进行界说其十分中心的意义和价值是：

• 寻找一个普适性十分好，被广阔用户所了解的风格/架构能够大规模下降用户的学习本钱，承受本钱，运用本钱；
• 能够在必定程度上表现出团队的专业性，能够给用户交给一种安全感；

就现在而言，RESTful风格的API现已得到了广阔开发者的认可，而且在市场上占有较高的运用比例，所以彻底能够以RESTful风格为敞开API的风格，并借力其周边生态（例如Apache基金会的OpenAPI标准等）。

4.1.3 标准是一种强束缚 - 以阿里云函数核算部分API为例

假如将风格比方成API的气质，是开发者的品德束缚；那么标准则是法令条款，是一种强束缚。因为单纯的“品德束缚”是没办法规约清楚具体的作业，它是一种弱束缚，所以针对已有的风格，提出一种标准是十分必要的。这种强束缚需求以一种文档输出，例如Google Cloud的规划文档。

如上图所示，一般状况下，在API规划攻略中要包含资源、办法、过错、字段等几个大类的规约，其中心意图是能够让开发者和运用，辅佐最小的本钱，得到最高功率的开发体会。以现在阿里云函数核算产品为例，依据上图所展现的一个规划攻略，对相关部分进行规划。

4.1.3.1 资源

4.1.3.1.1 资源品种

首要要明晰，阿里云函数核算产品现在一切的资源品种，并将这些资源进行笼统和界说，以其中部分资源为例：

• 服务（Service）：service
• 函数（Function）：function
• 触发器（Trigger）：trigger
• 自界说域名（CustomDomain）：custom-domain
• 版别（Version）：version
• 别名（Alias）：alias

4.1.3.1.2 资源联系

对资源品种进行界说，有助于整理产品的具体资源，可是资源之间是存在着必定的联系的，所以在对资源品种界说后，还需求对资源联系进行进一步的剖析。以服务、函数、触发器三个资源为例，确认彼此之间的联系：

4.1.3.1.3 资源的上层笼统

除了资源品种以及资源联系之外，必要时还需求依据周边产品界说的API，以及本身产品的拓展性，进行一些资源的笼统，或许说是进行资源的上层首相。因为用户在运用阿里云函数核算产品还包含运用、项目等概念，所以能够在上层独自笼统出一个运用的概念，也算是与其他产品联动时做相关：

• 运用（Application）：application

4.1.3.1.4 资源特点

既然有资源存在，那必定就要有资源的相关描绘。关于资源的相关描绘，能够界说为是资源的特点。对资源特点的界说有助于大盘特点的共同性，共同性，也有助于更标准，科学的描绘资源。不同资源会有不同的特点，此处仅以函数核算的服务、函数两个资源举例阐明：

• 服务（Service）：service

  • name: 称号
  • region：区域
  • vpc：网络
  • logs：日志

• 函数（Function）：function

  • name: 称号
  • runtime：运行时
  • timeout：超时
  • memory-size：内存

4.1.3.1.5 资源的数据结构

针对上面的资源品种、联系以及资源的特点等，能够对资源的数据结构进行规约。能够从资源、特点两个层面进行规约，例如：

• 资源层级：

  • 服务: /services/{service-name}
  • 函数: /services/{service-name}/functions/{function-name}
  • 触发器: /services/{service-name}/functions/{function-name}/triggers/{trigger-name}

• 特点层级：

  • 服务：

  { "Name": "称号", "Region": "区域", "Vpc": "网络", "Logs": "日志" }

  • 函数：

  { "Name": "称号", "Runtime": "运行时", "Timeout": "超时", "MemorySize": "日志" }

此刻的数据结构仅仅一个十分简略的数据结构，尽管能够比较直观的展现，可是却不能被直观的描绘，例如参数的必要性、取值规模、取值类型等。所以这一部分能够参阅OpenAPI 3.0的标准，对特点进行规约，包含：

• 描绘
• 取值
• 是否必填
• ......

以Path字段为例：

paths:
  /services/{service-name}:
    description: '服务相关操作' summary: '能够进行服务的查询与服务的晋级，删除' get:
      description: '获取服务概况' operationId: get service information
      tags:
        - service  - get parameters:
        - name: service-name in: path
          description: 服务称号
          required: true schema:
            type: string
        - name: Aignature in: cookie
          description: 用户签名
          required: true schema:
              type: string

能够看到，经过这样一个描绘，不只能够清楚的知道途径的结构，还能够对参数等有一个比较直观，明晰的界说。

4.1.3.1.6 自界说资源

在标准拟定的进程中，自界说资源的标准是十分重要的。即便在上层做了足够的笼统，跟着事务的不断开展，API相关资源也会呈现比较显着的晋级，此刻就会呈现一些之前没有笼统和界说的资源；当然，因为某些事务的特点，也或许呈现某些特别的资源没有被笼统。在进行资源自界说时，一般需求明晰：

• 资源名：

  • 只能是名词；
  • 必需求小写；
  • 链接符一律用'-'；

• 资源特点：

  • 特点有必要用JSON表达；
  • 特点名只能用名词；
  • 特点名有必要小写；
  • 特点名链接符一律用'-'；
  • 特点规约时要明晰取值的类型；

• 资源与其他资源的相相联系：

  • 要写出上基层的联系，以及是否有必要存在；

4.1.3.2 办法

4.1.3.2.1 上层笼统办法

相同以阿里云函数核算产品为例，在日常运用进程中一般会有一些通用的办法，例如获取服务列表、获取函数列表、获取触发器列表、获取版别列表、获取别名列表等，相似于这种比较通用的办法，在标准拟定的时分是要进行共同笼统的，例如阿里云函数核算部分笼统的办法能够包含：

• 获取资源列表：LIST
• 获取资源概况：GET
• 删除资源：DELETE
• 晋级资源：UPDATE
• 创立资源：CREATE

4.1.3.2.2 上层笼统办法与HTTP映射

因为办法需求与HTTP有比较明晰的映射，所以在笼统办法之后，还需求对上层笼统的办法与HTTP进行有效映射，这种映射相同不行呈现二义性。相同以上面笼统的办法为例，对应的办法与HTTP办法的映射能够是：

• 获取资源列表：LIST

  • 映射为GET办法
  • 获取服务列表：GET /services

• 获取资源概况：GET

  • 映射为GET办法
  • 获取服务列表：GET /services/{service-name}

• 删除资源：DELETE

  • 映射为DELETE办法
  • 获取服务列表：DELETE /services/{service-name}

• 晋级资源：UPDATE

  • 映射为POST办法
  • 获取服务列表：POST /services/{service-name}，一起JSON作为恳求体，传入改动资源的特点和取值

• 创立资源：CREATE

  • 映射为POST办法
  • 获取服务列表：POST /services/{service-name}，一起JSON作为恳求体，传入创立的资源特点和取值

4.1.3.2.3 自界说办法

与资源一样，尽管咱们笼统出来了许多上层办法或许通用办法，可是因为事务的多样性以及复杂性，在实践出产进程中，往往还需求对自界说办法进行标准。自界说办法指的是，有一些办法或许在上面的内容中未触及到，可是实践发生了，例如在未来运用函数核算的时分，或许会有中止实例，那么此刻就能够规约一个标准：

/some/resource/name:customVerb

例如，暂停某个函数的某个实例就能够是：

POST /services/{service-name}/functions/{function-name}/instances/{instances-id}/name:stop

4.1.3.3 过错

4.1.3.3.1 过错状况码

在RESTful的标准中，一般会运用HTTP的状况码进行过错状况的描绘，以阿里云函数核算产品为例，能够经过HTTP的状况码进行一些过错类型的判定，以400、403、404、500等相对简略的过错码为例：

• 400：参数、途径等相关问题
• 403：权限等相关问题
• 404：资源不存在等相关问题
• 500：体系过错等相关问题

4.1.3.3.2 过错码/多级

在实践出产中，因为事务的过错往往是十分复杂的，单纯依托某些状况码是没办法更好的做过错的捕捉或许定位，此刻能够考虑过错码的引进以及多级过错码的引进，相同以阿里云函数核算常见的过错为例：

• 400:

  • InvalidArgument：参数无效
  • MissingRequiredHeader：缺失必要的恳求Header
  • PathNotSupported：恳求的API途径不正确
  • EntityTooLarge：函数的入参太大

• 403：

  • AccessDenied：账号权限不足
  • SignatureNotMatch：恳求的数字签名不匹配
  • InvalidAccessKeyID：传入的AccessKey ID不正确

• 404：

  • ServiceNotFound：服务不存在
  • AliasNotFound：别名不存在
  • DomainNameNotFound：域名不存在
  • VersionNotFound：版别不存在

• 500：

  • InternalServerError：内部过错

当然假如事务触及到的服务/产品过多，也能够考虑多级过错码，例如

• 400:

  • InvalidArgument：

    • TypeError：类型过错
    • RangeError：取值规模过错

4.1.3.3.3 自界说过错

所谓的自界说过错是说，在实践出产进程中，所提取出来的通用的过错码实践上并不能满意一切事务诉求，却是在必定的时分有一些事务需求自界说过错码，所以此刻需求给出自界说过错的标准：

• 大驼峰方式
• 具有必定的笼统才干
• 悉数为名词

4.1.3.3.4 过错呼应结构

此处需求规约一个过错的呼应结构，例如Google Cloud的结构为：

{ "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "status": "INVALID_ARGUMENT", "details": [
      { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "API_KEY_INVALID", "domain": "googleapis.com", "metadata": { "service": "translate.googleapis.com" }
      }
    ]
  }
}

能够在此根底上，界说咱们的多级过错结构：

{ "error": { "code": 400, "message": "Type error message", "status": ["InvalidArgument", "TypeError"] "details": [
      { "reason": "API_KEY_INVALID", "domain": "example.com", "metadata": { "service": "fc.aliyun.com" }
      }
    ]
  }
}

4.1.3.4 字段

4.1.3.4.1 命名标准

在定制相关的标准中，要明晰命名的意义：

• 简略
• 直观
• 共同

所以，就要对命名进行一个具体的规约，例如：

• url参数悉数选用小写，用"-"进行参数链接;
• 恳求体参数悉数选用大驼峰方式；

4.1.3.4.2 组合笼统

能够供给一些独自的笼统词汇，供用户组合。

例如：动词create和名次time组合到一起能够是：create-time或许CreateTime（依据不同位置，或许组合办法不同）；相似的笼统词汇能够有：get、list、create、update、remove、delete、service、function、trigger、version、layer等；

4.1.3.4.3 上层笼统

能够对一些通用的内容进行命名，这样有助于事务在运用的时分，将某些内容愈加共同和标准，例如：

• 创立时刻：CreateTime
• 运行时：Runtime
• 内存束缚：MemorySize

除此之外还应该多一些固定的，常用的缩写进行笼统提取：

• config (configuration)
• id (identifier)
• spec (specification)
• stats (statistics)

4.1.4 东西是履行规矩，是终究收口与共同性的确保

工欲善其事，必先利其器。若想在多团队协作的方式下，大规模交给高质量、高共同性的RESTful API及配套产品，不只要有完善的流程和标准，更要有标准对应的查验东西，否则“总会有人在冒犯法令的边际线上不断试探”，此刻一个“共同API发布渠道”就显得尤为重要。无论是阿里云的POP团队，仍是腾讯云的云API团队，其都有一套自己的共同API发布渠道，经过这样一个共同渠道：

• 一方面能够确保所发布的API在必定程度上的共同性；
• 另一方面也便于办理和共同笼统API网关层的才干，以及便于愈加标准，共同的发布周边配套才干；

如上图所示，在这个API发布渠道上，根本人物（除体系办理员之外）首要分为事务开发，事务负责人，API网关团队；每个人物有每个人物的首要作业界容，整个渠道，经过不同人物的协同，大规模交给高质量、高共同性的RESTful API及配套产品。相同，在这个渠道上其首要功用包含产品/事务的办理，API的录入，测验，审阅，发布，一起也会包含API发布后的配套才干的发布，例如API、SDK、API Explorer、过错中心等。

渠道的优势：

• 能够让API正式对外露出的部分共同收口，进行共同的审阅，能够确保API的高度共同性；
• 能够最大或许性的确保API发布时的标准性和兼容性；
• 当标准高度共一起，更有利于上层共同笼统SDK，API文档以及API Explorer等才干；（假如标准不共同，哪怕只有细微距离，或许都会对上层的建造带来极大的保护本钱，包袱）
• 能够尽或许确保API的全体流程的标准性，经过屡次审阅和验证，能够尽或许的确保接口的安全和安稳；

或许带来的问题：

• 因为流程加长，在必定程度上会下降“敏捷性”；
• 因为需求在一个新的体系中保护API，或许会添加必定的学习本钱和运维本钱；

针对上面的问题，进行以下回答：

• 敏捷性是建立在安全和安稳的条件下，流程尽管添加，可是全体的安全性和安稳性得到了更大的确保，这是值得的；
• 引进一个新的体系意图，并不是引进一个“费事”，其中心价值在于后期正全体的保护流程的缩短和主动化，包含测验的主动化流程化等，也包含周边配套措施和服务的流程化、主动化；

4.2 对外东西的高度共同性建造计划

众所周知，一个大的产品往往是由内部多个部门协同进行研制，一个大的产品对外露出的API，往往也是由内部多个团队协同完结。可是对外露出时，外部用户并不会重视是多少个团队，重视的更多是功用是否完好，是否共同，对自己的开发、对接是否有帮助，自己是否能够信任这个团队。

此刻共同性就显得尤为重要，此刻的共同性其实是包含了几个方面：

• API的形状、风格、标准对外表现的共同性；
• 不同模块的的辅佐东西，以及东西的相关运用办法的共同性；

所以往往咱们的敞开API在对外露出之后，往往不只要有共同的API风格，标准，其周边的配套产品的共同性也是至关重要的，而配套产品的共同性在必定程度上高度依靠。

对外东西或许说时对外的配套产品共同性其实是对全体API标准的遵从程度的一种巨大的考验。试想，一个大型服务对外露出1000个RESTful风格的API，其中999个均遵从预订的标准和流程进行发布，其中有一个时特别的API，彻底不符合标准，此刻在进行对外的共同东西的封装，或许配套产品的生成，就要针对这一个API做额定的判别和处理，假如这类不标准的API不止是1个，而是十个，二十个，那么所带来的便是对外配套产品的安全性和安稳的巨大应战。

如上图所示，对外东西的高度共同性建造计划是要建造在内部风格的共同、标准的共同、流程的标准以及对外发布的API的共同性，只有这样才能够经过规矩，安全、安稳的生成共同风格的配套产品。

5 总结

综上所述，尽管RESTful API更多来说是一种风格，可是其凭借着近些年的开展，现已逐步的成为了API生态中的事实标准。跟着时刻的开展，不只有开发者普适性认同的RESTful标准，也有Apache基金会的明星项目OpenAPI3.0等；当然，各个厂商为了能够让自己的敞开API与本身事务匹配度更高，也逐步的推出定制化的RESTful风格的敞开API，这其中比较典型的比如是Github以及Google Cloud。

尽管RESTful这种风格十分流行，现已逐步成为领域内的事实标准，OpenAPI 3.0这些标准也日趋老练，行业界也有Google Cloud，Github这类优异的API规划文档作为参阅和学习，可是在怎样大规模交给高质量、高共同性的RESTful API及配套产品这个问题上，仍旧面临着巨大的应战。

本文经过腾讯如此API渠道以及阿里云POP渠道进行剖析，以阿里云Serverless产品为例，总结出：

• 流程是整个API从零到一的生命线；
• 风格是是API的气质，是品德束缚
• 标准是法令条款，是一种强束缚
• 东西是履行规矩，是终究收口与共同性的确保

即若想大规模交给高质量、高共同性的RESTful API及配套产品，咱们必定要从风格的明晰、标准的定制、东西的完善、流程的明晰入手，只有在完善、科学的流程下，让每个人都清楚风格，遵从标准，再经过东西进行强校验，审阅，收口，才有助于大规模交给高质量、高共同性的RESTful API，一起也有助于经过标准化、主动化的手段生成API文档、SDK，API Explorer等配套产品。

无论是腾讯云仍是阿里云，共同对外露出的敞开API渠道都是必不行少的收口东西；无论是Google Cloud仍是Github，一套优异的RESTful风格的API，都是离不开完善的标准文档，规划攻略的约好。