揭開雲的面紗，從雲的語言OpenAPI開始

阿裡雲作為國内乃至亞洲領先的IaaS雲廠商，提供了豐富的算力産品服務，以算力商品線上化的方式進行出售。目前階段算力商品的載體形态主要是執行個體規格。那麼，購買執行個體規格的OpenAPI （如RunInstances）也就最具IaaS雲的代表性。那麼，分析RunInstances接口（程式設計協定）也就最具典型性。

下面以阿裡雲OpenAPI RunInstances參數定義，進行‘語言’特性分析。

https://help.aliyun.com/document_detail/63440.html

語言的基本特性來解讀OpenAPI

OpenAPI指向性

指向性通知表示明确地表達、描述一個概念、實體、行動等。對于API指向性，意味着API的含義或者功能應首先避免二義性。

我們選擇RunInstances作為分析案例，那麼它指向什麼？ 開啟執行個體（Run），也就是雲上購買一批執行個體（Instance等價一定規模的算力）。從執行個體概念來說，RunInstance指向很明确：購買并啟動執行個體。

進一步分析執行個體之是以成為執行個體，且能區分其他執行個體，那麼執行個體應該具備更具體的‘區分性’的指向性。執行個體提供算力服務，由此執行個體的具體指向就是算力相關的具體指向。我們知道執行個體的算力展現：計算、存儲、網絡三大件，以及安全等核心要素。是以，RunInstances 裡面預期應該有這些算力相關的具體指向。那麼RunInstances 目前實際參數在這些具體指向性是怎麼展現的呢？

OpenAPI計算指向性

參照RunInstances API 定義，其中有如下參數，這些參數對計算進行了‘指向’。

參數名稱	資料類型	取值樣例
InstanceType	String	ecs.g6.large
InstanceName		k8s-node-[1,4]-alibabacloud
CpuOptions.Core	Integer	2
CpuOptions.ThreadsPerCore
CpuOptions.Numa		1

OpenAPI存儲指向性

參照RunInstances API 定義，其中有如下參數，這些參數展現了對存儲‘指向’性。

SystemDisk.Size		40
SystemDisk.Category		cloud_ssd
SystemDisk.DiskName		cloud_ssdSystem
SystemDisk.Description		SystemDisk_Description
SystemDisk.PerformanceLevel		PL0
SystemDisk.AutoSnapshotPolicyId		sp-bp67acfmxazb4p****
IoOptimized		optimized
StorageSetId		ss-bp67acfmxazb4p****
StorageSetPartitionNumber
DataDisk.N.PerformanceLevel		PL1
DataDisk.N.AutoSnapshotPolicyId
DataDisk.N.Encrypted		false
DataDisk.N.Description		DataDisk_Description
DataDisk.N.SnapshotId		s-bp17441ohwka0yuh****
DataDisk.N.Device		null
DataDisk.N.Size		2000
DataDisk.N.DiskName		cloud_ssdData
DataDisk.N.Category
DataDisk.N.DeleteWithInstance	Boolean	true
DataDisk.N.KMSKeyId		0e478b7a-4262-4802-b8cb-00d3fb40****

OpenAPI網絡指向性

參照RunInstances API 定義，其中有如下參數，這些參數展現了對網絡‘指向’性。

VSwitchId		vsw-bp1s5fnvk4gn2tws0****
InternetMaxBandwidthIn		10
InternetMaxBandwidthOut
Ipv6AddressCount
NetworkInterfaceQueueNumber		8
NetworkInterface.N.VSwitchId		vsw-bp67acfmxazb4p****
NetworkInterface.N.NetworkInterfaceName		Network_Name
NetworkInterface.N.Description		Network_Description
NetworkInterface.N.SecurityGroupId		sg-bp67acfmxazb4p****
NetworkInterface.N.PrimaryIpAddress		172.16.**.**
NetworkInterface.N.QueueNumber
NetworkInterface.N.SecurityGroupIds.N	RepeatList	sg-bp15ed6xe1yxeycg7****
PrivateIpAddress		10.1.**.**
Ipv6Address.N		Ipv6Address.1=2001:db8:1234:1a00::***

OpenAPI安全指向性

SecurityGroupId
Password		EcsV587!
PasswordInherit
RamRoleName		RAM_Name
SecurityGroupIds.N
SecurityOptions.TrustedSystemMode		vTPM
SecurityOptions.ConfidentialComputingMode		Enclave

小結

1. 分析RunInstances 不難發現，裡面還有其他的指向性屬性參數，這裡就不一一解說。
2. 計算、存儲、網絡、安全等這些參數有的是必須，有的非必需。非必需的都有預設值。例如InstanceType必須的，InstanceName非必須的。
3. 這些參數有的是基本屬性，有的是進階屬性。例如CpuOptions.Numa計算的進階特性，SecurityGroupIds.N基本安全組，SecurityOptions.TrustedSystemMode安全增強。
4. 計算、存儲、網絡、安全等構成具體的指向，并且這些具體指向因為各種組合關系，使得這種指向豐富度大大增強，也導緻真正了解具體商品對應的明細指向，有一定的成本。也間接反應了面向執行個體規格這種商品購買，具有一定的學習門檻。
5. 如果繼續存在InstanceType 這周雲産品售賣形态，意味着滿足指向型的RunInstances的各具體指向隻會更加複雜、更加多元。目前通過啟動模版、授權購買的方式可以簡化一些操作，本質并沒有‘單純面向概念’，例如執行個體規格進行互動。
6. 未來超越目前的指向有哪些可能。

1. 1. 一種可能的超越方式：例如安全是預設配置項，安全的相關配置按預設處理，那麼請求參數裡面可以省去這部分。
   2. 一種可能是新的執行個體規格出售，面向一個算力場景，例如雲桌面，其背後具體什麼樣的資源傳遞形态，使用者不感覺，使用者隻需感覺雲桌面本身的特性。
   3. 新的産品規格執行個體在某個産品代上就終止了，改為‘屬性、品牌’。老舊代執行個體被新的替代。這意味着：新的執行個體規格價格完全碾壓舊代執行個體，新的執行個體規格各方面性能都具備很強的能力，完全可以适應各種場景需求
   4. 面向算力或者服務的傳遞，屏蔽硬體、軟體的差異

OpenAPI 描述性

描述性意味着：對象具有靈活性，支援多種場景的需求，描述性用于更好了解。

描述性這裡狹義地了解對目前執行個體規格的描述說明，算一個輔助的介紹。

參照RunInstances API 定義, 可以将以下參數了解為描述性的内容。

RegionId		是	cn-hangzhou
ZoneId		否	cn-hangzhou-g
Description			Instance_Description

這些參數就是典型的針對具體指向的描述性參數。

整個RunInstances本身就是在描述雲上購買算力商品這麼一種‘程式設計協定行為’。

OpenAPI 邏輯性

邏輯性本質是按一定規則、條理來表達一種含義。參照RunInstances API 定義，下面的這幾個參數可以說是邏輯性的典型代表。

		必填性
LaunchTemplateId			lt-bp1apo0bbbkuy0rj****
LaunchTemplateName			LaunchTemplate_Name
LaunchTemplateVersion	Long		3

目前雲上商品形态主流的還是‘伺服器’這個具體實物形态，對應RunInstances的邏輯就是實作這一形态，支援購買生産一台伺服器的需要的各個邏輯參數、支援可程式設計化。幾乎任意一個API本身就是一種邏輯的表現。

OpenAPI 交際性

交際性通常是互動的方式進行，要求互動的雙方互相聽的懂、互相有響應。

對應RunInstances的交際性，意味着：RunInstance輸入參數應該支援

1. 服務端應該及時有響應

1. 1. 交際如果隻是單向的，這個互動是沒有‘靈魂’的。對于雲的API交際性的典型展現：接口響應要及時，否則就阻礙了高效互動。
   2. 相應應該和請求是關聯的，要求輸出相關結果。

1. 互動的響應，有積極的、消極的

1. 1. 接口回報有正确的、不正确的。對應接口結果，有成功的回報，失敗的回報，并且失敗有具體的原因、錯誤表達，便于下一輪的互動，這種結果應該符合互動的上下文、互動雙方能夠了解。

1. 可以反複進行

 阿裡雲的RunInstances的服務響應、結果輸出都有相關明确的定義，很好地展現了語言的’交際性‘

OpenAPI 傳播性

一種語言的傳播性意味着：語言交流的人群規模、人群使用的頻率。我們知道中文和英文在形成上是有很大的不同的，例如：語言文字的結構、文法、文法、句法的差異。追根溯源，本質是文化的差異。

那麼OpenAPI的傳播性，同樣意味着有多少人使用，使用頻率如何。前面說到RunInstance是阿裡雲目前商品售賣形态的主要代表，自然RunInstances是高頻使用的。而人群規模也就是雲的使用者規模。對比AWS、AliYun的接口，

OpenAPI 名族性

在這裡對應雲平台自身的特性。例如阿裡雲的RunInstances、華為的RunInstance、騰訊的RunInstance、AWS的RunInstance 具有各自平台的特性。沒有好壞之分，隻有合适與否的選擇。

語言的創新和實踐

OpenAPI作為雲的語言，作為一種使用者與雲，端與雲的互動、互動的程式協定。那麼創新性、實踐性尤為關鍵。

OpenAPI 創造性

對于接口協定，從使用方來說，一經定義，就不期望随意修改。越簡單越好，越是見名知意的表述越友好。從定義方來說，要能夠支援明确的語意，要能在一套接口協定上支援各種場景的需求，要能提供易用性同時支援靈活性。

參照RunInstances API 定義，不能發現其中 Tag的定義，就很好的‘創造性’展現。通過Tag使用者自定義自己的名詞的Key、Value，這些Key、Value可以實作财務、資源、管理的自定義處理，打開了‘On Cloud’的各種可能的‘二次處理’的大門。例如基于Tag的分賬，例如基于Tag的資源和應用分組關心管理，例如給予Tag的私有池比對排程等。

Tag.N.Key			TestKey
Tag.N.Value			TestValue

OpenAPI 結構性

任何語言都有其相關的基本詞彙、詞法、句法等結構性資訊。OpenAPI作為雲的語言，順着這個思路來看，那麼雲的所有OpenAPI構成了雲的語言，所有OpenAPI遵循一個統一的詞彙、詞法、句法規則。

對應RunInstances（看作一個句子），它的句法結構性，例如計算、存儲、網絡、安全、基本描述等。它的詞法結構性，單一概念指向的共同字首結構性。例如SystemDisk SecurityOptions等。

雲應該具備很強的實踐性，否則雲很難實作普惠。我們說雲提供的是‘可程式設計基礎設施‘，這個基礎實施對外的溝通語言是OpenAPI，OpenAPI是提供算力服務的，被內建到業務的代碼中。哪些因素會影響這種實踐性的‘品質’或者‘生命力’？回到詞彙、詞法、句法，對應具體接口，也就是接口的資料結構、接口的功能邊界、接口之間的連結。

目前看，OpenAPI的結構性AWS做的非常好，阿裡雲還有欠缺，為什麼這麼說。

1. 形式上，AWS 明确的列舉了它的平台上它提供的OpenAPI Data types，并且各接口嚴格遵守和使用這些Data types。看起來很簡單的形式，其實意味着：各個新的産品推出、服務接口的定義，首先要在整體雲的data types裡面進行比較，是否已有相關data types，新的data types 是否合乎規範。縱觀阿裡雲，并沒有這樣的data types 的目錄，這也就不難發現，為何阿裡雲的一些接口定義裡面出現了相同概念的多種參數命名。例如RunInstances的RegionId，DescribeSavingsPlansCoverageDetail https://help.aliyun.com/document_detail/298067.html 中的傳回對象是Region

例如

PurchaseReservedInstancesOffering

https://help.aliyun.com/document_detail/100032.html

參數名	參數類型	預設值	取值說明
OfferingType		All Upfront	預留執行個體券的付款類型。取值範圍： No Upfront：零預付 Partial Upfront：部分預付 All Upfront（預設）：全預付

QuerySavingsPlansInstance

https://help.aliyun.com/document_detail/198100.html

PayMode		total	付款類型： total 全預付 half 半預付 zero 0預付

1. 我們說AWS的産品之間的互通性很強，阿裡雲的産品之間很難一步到位。這什麼意思呢。例如你在阿裡雲購買了ECS、然後購買阿裡雲的RDS，然後期望ECS和RDS很easy的打通一起服務。在AWS上這塊的相對簡便些。 https://zhuanlan.zhihu.com/p/24721353

https://docs.aws.amazon.com/codecommit/latest/userguide/integrations.html

當然從另外一個“狡辯”角度可以說，阿裡雲的發展規模還沒有達到aws的規模，是以服務還不夠成熟，或者說API還不夠成熟。從設計視角看，阿裡雲在API目前的設計上存在的結構性缺陷。

OpenAPI 具體

具體性本質是原子性的另外一種說法。這裡其實有一個很模糊的邊界，究竟什麼概念或者實體範圍算一個原子呢，到底切多謝比較合适呢？

例如存儲接口的定義，從read、 write 的參數，哪一個粒度最合适，是byte、byte[]、string、object？

例如tags.Key、value 這裡是普通string，還是jsong string、還是其他自定義string 甚至加密string，那種合适？

具體性作者的經驗是：定義OpenAPI的時候，盡量從屬性原子開始定義、到接口功能原子定義結束，從‘概念實體‘具體化設計，到不同角色同學評審一緻結束。

OpenAPI 準确

準确性一種是本接口内部的準确性，一種是接口體系内的準确性。準确性第一直覺展現在接口命名上。例如create、delete、query，get、put、post、move等關鍵動詞的定義，以及instance、vpc、securityGroup等名詞的定義。

例如取消、釋放、删除，究竟是delete、cancel、release這樣的動詞，還是統一delete呢？

準确性作者的經驗是：應該首先遵循整體API的上下文環境（可能之前采取了某種風格，這種風格存在缺陷，不建議引入新的風格。因為新的又增加了使用者的學習成本），在這個環境下，努力做到準确（很難說有絕對的準确，可能在這個場景下很準确，在另外一個環境下，可能就存在歧義了）。單個接口的準确性應該努力做到極緻的‘合理’。多個接口之間的準确性，依賴工具的統一檢測和管理、參照業界通用的做法

OpenAPI 簡練

簡練首先要做到一個接口隻做一件事情。如果一個接口做多個事情，那麼這個接口相比一件事就不夠簡練了。

不論以什麼方式來看雲的OpenAPI，不論以什麼設計準則來設計和實施雲的OpenAPI，本質的不會變：做到簡單、易用、可靠。回到接口設計本身的技術經驗，業界有很多成熟的經驗可以拿來學習（不一定能直接照搬到工作中，可能有一些技術債務不允許做優化----優化可能又引入新的 不一緻）

下面列舉Google、Aws、Azure的接口設計實踐文檔，這些文檔還是滿值得反複學習、借鑒的。

https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design https://docs.microsoft.com/en-us/azure/architecture/microservices/design/api-design https://aws.amazon.com/startups/start-building/how-to-build-a-public-facing-API/ https://aws.amazon.com/api-gateway/api-management/ https://cloud.google.com/blog/products/api-management/google-cloud-api-design-tips https://developers.google.com/google-ads/api/rest/design/overview https://cloud.google.com/apis/design/

總結

如何學習API設計，特别是雲的API設計，從購買建立執行個體RunInstances開始吧。

實施好單個API、以及和生态整體API的協調一緻，可以借鑒語言的基本特性來反問自己，是否可以進一步優化下？

最終總有一些坑，一些前人的經驗教訓可以提前學習，提前規避掉，那麼業務的API設計文檔，值得反複學習