TeaDSL: A Multi-language SDK Solution for All API Gateways

Background

Puling is an engineer at Alibaba Cloud. He is an ardent lover of open source technologies and is one of China’s top experts active on GitHub. In his sixth year with the company, he considered quitting his job to join a startup. And while he was deliberating the decision and pondering his work, he felt that Alibaba Cloud had earned its reputation for providing excellent cloud computing services and products, which were popular choices among startups. But even so, since he had written many SDKs for Node.js, he knew that there was still room for improvement in Alibaba Cloud’s developer experience. He decided, out of his passion for programming, that he would stay and try to improve the situation. He then joined Alibaba Cloud Open Platform and dedicated himself to the optimization of SDKs. TeaDSL is a patented solution developed by Puling and his team. The following sections share his thoughts on and understanding of using TeaDSL as a multi-language SDK solution.

Problems with OpenAPIs

An old practice for OpenAPI design was creating a service interface, sketching out the documentation, then leaving the OpenAPI to customers without further refinement. The provider would assume that the design part was complete, and not care about the user experience.

Figure 1. 1st-generation OpenAPIs are composed of interfaces and have ill-defined documentation.
Figure 2. 2nd-generation OpenAPIs can be implemented by SDKs, but this implementation is only supported by a few languages.
  • An SDK is required for better developer experience, and features like the detail encapsulation and IDE auto-completion must be implemented.
  • Documentation must come with code samples to demonstrate real-world use-cases.
  • CLI can also be provided to make writing Bash scripts easier.
  • Test cases are a must for practicing continuous integration and performance assurance.
Figure 3. As the number of consumers increases, OpenAPI providers need to develop a more comprehensive set of tools and offer support for more programming languages.
Figure 4. Multiple kinds of OpenAPIs and API gateways are used as the platform of a company grows.

How TeaDSL Works

TeaDSL is a domain-specific language (DSL) designed by the Alibaba Cloud Open Platform SDK team. It is applied in the following scenarios:

  • It is translated to generate code in other languages. In other words, it allows the generation of SDKs in different languages with unified intermediate representation.
  • We can consider a collection of OpenAPIs as a library on account of the intermediate representation, and then write code samples on this basis to achieve the unified generation of code samples for multiple languages.
Figure 5. The workload for providing SDKs in N programming languages for M gateways is M * N.
Figure 6. The workload becomes M + N with the aid of TeaDSL.

TeaDSL and API Gateways

Different API gateways or OpenAPIs of different products may have very dissimilar styles. One could even say that the OpenAPIs of each style have a particular metadata format. The preferred approach, in this case, is to adopt standardized formats for OpenAPI descriptions, for example, Swagger. Built around the OpenAPI Specification, Swagger is backed by a large ecosystem of tools and has become the industry standard for RESTful OpenAPI design.

  • Develop a tooling ecosystem based on these standards to expand the functionality.

Design of New Standards

We found that OpenAPIs are always based on the HTTP protocol stack, no matter what parameters are present in the endpoint and regardless of what protocol is used to transport data, be it JSON, XML, or even a custom protocol. The central theme remains the same: HTTP. Therefore, we have designed a rudimentary data model as follows:

{
protocol: string, // http or https
port: number, // tcp port
host: string, // domain
request: {
method: string, // http method
pathname: string, // path name
query: map[string]string, // query string
headers: map[string]string, // request headers
body: readable // request body
},
response: {
statusCode: number, // http method
statusMessage: string, // path name
headers: map[string]string, // response headers
body: readable // response body
},
}
model User {
username: string,
age: number
}
toJSON(user: User): string
toXML(user: User): string
__request.body = toJSON(user);
__request.body = toXML(user);
api getUser(username: string): User {
__request.method = 'GET';
__request.pathname = `/users/${username}`;
__request.headers = {
host = 'hostname',
};
} returns {
var body = readAsJSON(__response.body);
return body;
}
  • Several methods, such as toJSON, toXML, and readAsJSON, are introduced to separate the data structure from the serialization process.
  • The process is wrapped into a method.
function toXML(data: $Model): string;
function toJSON(data: $Model): string;

TeaDSL and Programming Languages

Using one description format to describe OpenAPIs is only half the work. TeaDSL still needs to take the description language as a single source and generate output in different languages. We used to take the template-based code generation as the means of multilingual support. However, this still has some drawbacks:

  • The generated code is prone to naming conflicts and syntax errors.
  • Create OpenAPI-related code samples in multiple languages.
  • Create OpenAPI-related test cases in multiple languages.

Summary

The main features of TeaDSL are that it supports OpenAPIs of different styles and the generation of SDKs and code samples in multiple languages. The ultimate goal is to achieve consistency in all OpenAPI usage scenarios, such as definition, documentation, SDK generation, and CLI support. The uniform, professional, and consistent performance of TeaDSL significantly alleviates the workload of OpenAPI providers and reduces the frequency of human error.

Original Source:

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store