Unveil the cloud, starting with the language OpenAPI of the cloud-Alibaba Cloud Developer Community

As a leading IaaS cloud manufacturer in China and even in Asia, Alibaba Cloud provides a wide range of computing power products and services, and sells computing power products online. At the current stage, the carrier type of computing power products is mainly instance types. Therefore, OpenAPI that purchase instance types (such as RunInstances) are the most representative of IaaS cloud. Then, RunInstances analysis interface (programming protocol) is the most typical.

 

The following section uses Alibaba Cloud OpenAPI RunInstances parameter definitions to analyze the language features.

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

 

OpenAPI directivity

directional notification means clearly expressing and describing a concept, entity, action, etc. API directivity means that the meaning or function of an API should be avoided first.

We choose RunInstances as an analysis case, then what does it point? To enable an Instance (Run), you can purchase a batch of instances on the cloud (Instance equivalent to a certain scale of computing power). In terms of instance concept, the RunInstance point is clear: purchase and start an instance.

To further analyze the reason why an instance becomes an instance and can distinguish other instances, the instance should have a more specific "differentiation" orientation. The instance provides computing power. The specific direction of the instance is the specific direction related to computing power. We know that the computing power of an instance is represented by three major components: computing, storage, network, and security. Therefore, the RunInstances is expected to have specific directions related to these computational forces. So how do the current actual parameters of RunInstances reflect these specific directivity?

 

OpenAPI-computing directivity

according to the RunInstances API definition, the following parameters are used to 'direct 'the calculation'.

OpenAPI storage orientation

the following table describes the parameters defined by RunInstances API. These parameters indicate the 'direction' of storage.

 

OpenAPI network orientation

the following table describes the parameters defined by the RunInstances API. These parameters indicate the "direction" of the network.

OpenAPI security orientation

the following table describes the parameters defined by the RunInstances API. These parameters indicate the "direction" of the network.

summary

1. RunInstances analysis, it is not difficult to find that there are other directional attribute parameters, which will not be explained here.
2. Computing, storage, network, security, and other parameters are required, while others are not. Default values are available for non-required instances. For example, InstanceType required, InstanceName not required.
3. Some of these parameters are basic attributes and some are advanced attributes. For example CpuOptions. Advanced features of Numa computing, SecurityGroupIds.N basic security group, SecurityOptions.TrustedSystemMode security enhancement.
4. Computing, storage, network, security, etc. constitute specific directions, and these specific directions are greatly enhanced due to various combinations of relationships, it also leads to a certain cost to truly understand the detailed orientation of specific products. It also indirectly reflects the purchase of instance-oriented products, which has a certain learning threshold.
5. If the sales pattern of cloud products continues to exist InstanceType this week, it means that the specific directions of the targeted RunInstances will only be more complex and diversified. At present, some operations can be simplified by starting templates and authorizing purchases. In essence, they are not concept-oriented, such as instance type interaction.
6. What are the possibilities of going beyond the current direction in the future.

1. 1. A possible solution: for example, security is the default configuration item, and security-related configurations are processed by default. This parameter can be omitted in the request parameters.
   2. One possibility is that new instance types are sold for a computing power scenario, such as Cloud Desktop. Users are not aware of what kind of resource delivery is behind it, users only need to perceive the features of the cloud desktop itself.
   3. The new product specification instance is terminated on a product generation and changed to 'attributes, brand '. Old instances are replaced by new instances. This means that the price of the new instance type will completely crush the old instance. The new instance type has strong performance in all aspects and can fully meet the needs of various scenarios.
   4. Facing the delivery of computing power or services, shielding the differences between hardware and software.

OpenAPI descriptive

descriptive means that objects are flexible and support the needs of various scenarios. Descriptive is used for better understanding.

Description This is a description of the current instance type in a narrow sense.

The following parameters can be understood as descriptive by referring to RunInstances API definitions.

these parameters are typical descriptive parameters for specific directions.

The entire RunInstances itself describes the "programming protocol behavior" of purchasing computing power products on the cloud '.

 

OpenAPI logic

the nature of logic is to express a meaning according to certain rules and rules. Referring to the definition of RunInstances API, the following parameters can be regarded as typical representation of logic.

1.

Currently, the mainstream of the product form on the cloud is the specific physical form of 'server'. The logic of the corresponding RunInstances is to implement this form, which supports various logical parameters required to purchase and produce a server, supports programmable operations. Almost any API itself is a logical representation.

 

OpenAPI communicative

communication is usually conducted in the form of interaction, which requires both sides of the interaction to understand each other and respond to each other.

The interoperability of the corresponding RunInstances, which means that RunInstance input parameters should support

1. the server should respond in a timely manner.

1. 1. If communication is only one-way, this interaction has no "soul. Typical embodiment of API communication in the cloud: API response must be timely, otherwise efficient interaction is hindered.
   2. The request must be associated with the request.

1. Interactive response, positive and negative

1. 1. the API feedback is correct and incorrect. Corresponding to the interface results, there are successful feedback, failure feedback, and the specific cause of the failure, error expression, convenient for the next round of interaction, this result should be in line with the context of the interaction, both sides of the interaction can understand.

1. Can be repeated

the service response and result output of Alibaba Cloud RunInstances are clearly defined, which reflects the language's "interchangeability'

 

OpenAPI transmissibility

the spread of a language means: the population size and frequency of language communication. We know that there are great differences in the formation between Chinese and English, such as the differences in the structure, grammar, grammar and syntax of languages. Tracing back to the source, the essence is cultural differences.

Then the spread of OpenAPI also means how many people use it and how often it is used. RunInstance mentioned above is the main representative of Alibaba Cloud's current product sales pattern. Naturally, RunInstances are frequently used. The number of users in the cloud. Compared with AWS and AliYun interfaces,

 

OpenAPI nationality

the features of the cloud platform are described here. For example, Alibaba Cloud RunInstances, Huawei RunInstance, Tencent RunInstance, and AWS RunInstance have their own platform features. There is no distinction between good and bad, only the choice of whether it is suitable or not.

 

as the language of the cloud, OpenAPI is a program protocol for interaction and interaction between users and the cloud and between clients and the cloud. Then innovation and practicality are the key.

OpenAPI creative

as for the interface protocol, the user does not want to modify it at will once it is defined. The simpler the better, the more well-known the expression is, the more friendly it is. In terms of definitions, it is necessary to support clear meanings, support requirements in various scenarios in a set of interface protocols, and provide ease of use and flexibility.

Referring to the definition of RunInstances API, the definition of Tag cannot be found, which is a good reflection of "creativity. You can use tags to customize the keys and values of your nouns. These keys and values can be used to customize finance, resources, and management, it opens the door to various possible 'secondary process' of 'On Cloud. For example, Tag-based sub-accounts, such as Tag-based resource and application group management, such as Tag-based private pool matching scheduling.

 

OpenAPI structural

any language has its related basic vocabulary, lexical, syntactic and other structural information. OpenAPI, as the language of the cloud, following this idea, all the OpenAPI of the cloud constitute the language of the cloud, and all OpenAPI follow a unified vocabulary, lexical, and syntactic rules.

Corresponding to RunInstances (as a sentence), its syntactic structure, such as computing, storage, network, security, basic description, etc. Its lexical structure and the common prefix structure that a single concept points. For example SystemDisk securityOptions.

 

The cloud should be very practical, otherwise it is difficult for the cloud to achieve inclusive benefits. We say that the cloud provides a "programmable infrastructure". The external communication language for the implementation of this infrastructure is OpenAPI,OpenAPI provides computing power services and is integrated into the business code. What factors will affect this kind of practical "quality" or "vitality '? Return to vocabulary, morphology, and syntax, corresponding to specific interfaces, that is, the interface data structure, interface functional boundaries, and links between interfaces.

At present, OpenAPI structure AWS well done, Alibaba Cloud still lacks , why do you say so.

1. Formally, AWS clearly lists the OpenAPI Data types it provides on its platform, and each interface strictly complies with and uses these Data types. It seems to be a simple form, which actually means that when new products are launched and service interfaces are defined, we first need to compare the data types of the entire cloud to see if relevant data types exist, whether the new data types comply with the specifications. Throughout Alibaba Cloud, there is no such directory for data types, which is not difficult to find, why many parameter names with the same concept appear in some API definitions of Alibaba Cloud . For example, RunInstances RegionId, DescribeSavingsPlansCoverageDetail https://help.aliyun.com/document_detail/298067.html中的返回对象是Region

for example

PurchaseReservedInstancesOffering

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

 

 

QuerySavingsPlansInstance

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

 

1. we say that AWS products are highly interconnected, and it is difficult for Alibaba Cloud products to achieve one-step communication. What does this mean. For example, if you purchase an ECS instance in Alibaba Cloud and then purchase an RDS instance in Alibaba Cloud, you can expect the ECS instance and RDS instance easy to get through services together. It is relatively simple on AWS. https://zhuanlan.zhihu.com/p/24721353

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

from another "sophistry" perspective, we can say that Alibaba Cloud's development scale has not reached the scale of aws, so the service is not mature enough, or the API is not mature enough. From the design perspective, Alibaba Cloud there are structural defects in the current API design.

 

 

OpenAPI specific

the nature of concretization is another statement of atomicity. In fact, there is a very fuzzy boundary here. What is the concept or entity range that is an atom? Is it appropriate to thank each other?

For example, the definition of the storage interface, which of the read and write parameters is the most appropriate granularity, byte, byte[], string, object?

For example tags.Key, value, this is a normal string, or jsong string, or other custom string even the encryption string, that that suits?

The concrete author's experience is: when defining OpenAPI, try to start from the attribute atom definition, to the end of interface function atom definition, from the concrete design of "concept entity" to the consistent end of review by different roles and classmates.

OpenAPI accurate

one is the internal accuracy of this interface, and the other is the accuracy within the interface system. The first aspect of accuracy is directly reflected in the interface naming. For example, define key verbs such as create, delete, query,get, put, post, and move, and define nouns such as instance, vpc, and securityGroup.

For example, cancel, release, and delete. Are they verbs such as delete, cancel, and release, or unified delete?

ACCURACY The author's experience is that the context of the overall API should be followed first (some style may have been adopted before, and this style has defects, so it is not recommended to introduce new styles. Because the new also increases the learning cost of users), in this environment, strive to be accurate (it is hard to say that it is absolutely accurate, it may be very accurate in this scenario, in another environment, there may be ambiguity). The accuracy of a single interface should be perfectly 'reason '. The accuracy of multiple interfaces depends on the unified detection and management of tools.

OpenAPI concise

the first thing to be concise is to do only one thing with one interface. If one interface does multiple things, this interface is not concise enough compared with one thing.

 

Summary

no matter how the cloud OpenAPI is viewed, no matter what design criteria are used to design and implement the cloud OpenAPI, the essence will not change: simple, easy-to-use, and reliable. Back to the technical experience of interface design itself, the industry has a lot of mature experience to learn (may not be directly copied to work, there may be some technical debts that cannot be optimized ---- optimization may introduce new inconsistencies)

the following lists the interface design practice documents of Google, Aws, and Azure, which are worth learning and learning from.

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/

 

how to learn API design, especially cloud API Design, start with purchasing and creating an instance RunInstances.

To implement a single API and coordinate it with the entire ecosystem API, you can refer to the basic language features to ask yourself whether you can further optimize it?

In the end, there are always some problems. Some previous experiences and lessons can be learned in advance and avoided in advance. Therefore, the API design document of the business is worth learning again and again.