Uni API: A Unified Cross-End API Solution for Xianyu

By Yeyao from Xianyu Technology

Background

With the gradual disappearance of client side traffic dividends, out-of-end placement has become one of the important drivers of seeking business growth. However, there are frontend containers born in different application scenarios and different periods on different apps:

Browser-based Webview containers (h5)
React Native and Weex containers derived from client-based rendering
Flutter containers based on self-drawing rendering
Small program containers with open platform capabilities

When the business crosses ends, the frontend teams need to evaluate and adapt the target environment one by one. In the initial stage, the frontend is usually supported by maintaining multiple sets of implementations for different target environments for the same business, which multiplies the workload. Cross-end solutions have been created for efficiency improvement.

Definitions

There is usually a large number of duplicate logic for cross-end JS API calls in the frontend code of the cross-end business:

if (isH5) {
  if (isXianyu) {   // Xianyu
    webXianyuToast();
  }else if (isTaobao) { // Taobao
    webTaobaoToast();
  } else if(isAlipay){ // Alipay
    webAlipayToast()
  }
  // ...
} else if(isWeex)
// ...

These calls typically go through the following path from development to online:

Determine the target environment with business teams, such as H5 (Alipay, Taobao, Tmall, etc.)
Ask the target container maintainer about how the API is called
Debug and develop in different environments
Test teams use different models to adapt on different apps.

Each step is a relatively time-consuming physical task. Hypothetically, it can meet the availability, usability, richness, and scalability so that the business can directly develop the following code and go online after normal testing. What problems should a cross-end API solution solve, and what capabilities should it provide?

import toast from  'uni-toast'

toast()

Availability: It adapts to frontend containers and apps (such as Webviews, applets, and WAPs) that are commonly available for business. It maximizes the use of API capabilities → calls app customization capabilities → calls container general capabilities → WAP environment simulation capabilities → returns support information to avoid abnormal calls
Usability: It provides reliable and fast debugging support for API calls in different environments.
Richness: It provides enough target environments and API collections to meet most of the business demands.
Scalability: With the development of business, it can support more apps and APIs. With the development of frontend technology, it can support more forms of containers.

Scheme Design and Implementation

Overall Design

In the initial stage of the project, I learned that Xianyu and the frontend supporting the cross-end business of the entire Alibaba economy have the same problem. Therefore, the cross-end API project starts from the perspective of the economy and is promoted in a co-construction manner. The solution design for the preceding problems is listed below:

We define the overall cross-end API solution as three parts: specifications, SDKs, and supporting facilities:

The specifications serve as a cross-end API standard to eliminate differences, making upper-layer services perceive only one set of specifications.
The SDKs follow the specifications and call the same underlying APIs in different environments to eliminate differences. Customizable and extensible cross-end API products are revealed through engineering capabilities, such as custom construction and split-end construction.
Supporting facilities provide quick retrieval capabilities through the API documentation and CANIUSE tools and quick trial capabilities through one-code multi-end call examples

Specification Formulation

The meaning of the cross-end API specifications is listed below:

For upper-layer business – It provides reference standards for SDK layer API design and improves the certainty and rationality of use on the business side.
For lower-layer business – It provides reference standards for JSAPI design at the Native layer to slow down the trend of underlying differentiation.

Whether the specifications can be widely promoted and maintained depends on its rationality and upstream and downstream recognition. To ensure the two points above, authors of existing cross-end solutions in the economy are invited to set up a cross-end API specification group to formulate cross-end API specifications from the following four aspects:

1. Scope: What kind of API should be counted as a cross-end API?

Cross-end APIs should have cross-end attributes and high-frequency attributes: Cross-end attributes can be objectively reflected by the support of each container. On the one hand, high-frequency attributes are based on the call statistics of each scheme. On the other hand, they are judged by voting by members of the cross-end specification group one by one.

2. Environment Probe: The core of cross-end APIs is to call the corresponding implementation based on different environments. Accurate environment identification is particularly important.

Environmental identification involves standard containers and special containers inside and outside the economy. In the environmental probe specifications, the whole scenario is covered by the combination mechanism of container identification protocol, end identification protocol, system identification protocol, and identification order convention.

3. Standard API Definition: The standard API model is the interface of real APIs and the framework of all APIs.

Through the analysis of the standard API collection, the differences between APIs are mainly reflected in four parts: method naming, call method, output and input parameter structure, and returning error code. These four parts plus the input and output parameter extension mechanism define the standard API model.

4. Extension Mechanism: It is supported by customization and extension capabilities in scenarios that are not covered by the standard API collection. Extend a new end container implementation based on a standard API or extend a new API.

SDK Implementation

We began to implement the SDK using the specifications as the implementation basis and guidance. In the whole process, we mainly faced the following challenges:

[Implementation] Huge Maintenance Workload: 55+ APIs are adapted to 8 containers and 30+ apps for long-term maintenance, and the number of APIs and environments do not decrease.
[Engineering] Multi-Scenario Product Output: Multi-scenario use → multi-form product. For example, the expected usage mode for daily business development is window.uni.toast(). The mode for cross-end basic material development is import toast from 'uni-toast' . The use in multiple scenarios requires multi-form output.
[Engineering] Customizability of the Scheme: From the perspective of the economy, scenarios are not only for Xianyu's business. Business-side scenarios usually require a part of the container environment supported by the delivery solution. Using the entire solution introduces unnecessary redundancy. Therefore, the solution needs to support the ability to define and build subsets from the complete set.

The key solution to the preceding challenges is:

Layered and End-to-End Adaptation of APIs: API differences are distributed in the container layer and app layer. When the SDK is designed, the differences are eliminated according to each layer. The container layer eliminates common API differences, and the app layer is customized based on the container layer. The design of end-to-end adaptation brings natural extensibility. When supporting a new end, only the corresponding API adaptation set needs to be implemented. The rest of the environment identification, API mounting, and multi-dimensional output package are completed by the project and uniapi-core.

Open Solutions Extend Capabilities and Reduce Centralized Maintenance Workloads: The priority is ensuring API maintenance of high-frequency apps and containers. When the target environment for cross-end delivery of services is not adapted, adaptation can be carried out according to specifications through co-construction. In addition, an app adaptation, maintenance, and claim mechanism are established to make the maintenance of multi-end adaptation long-term.
Custom Construction Capabilities: The design and combination mechanism of an atomized API can give the whole solution the ability to customize the construction.
Atomized API: The API adaptation on the specified container and app is used as the minimum unit to implement without side effects.
Combination Mechanism: The API is combined for construction and released automatically in code templates after configuring and extracting the required API and the target delivery environment.

If you have an environment-wide API atomization implementation, you can build a cross-end API solution with any degree of support. Several BU-level custom packages have been delivered.

Supporting Facilities Construction

The specifications and SDKs meet the requirements of availability, richness, and scalability. In terms of usability, cross-end APIs provide query and debugging capabilities for complex APIs, and internal and open-source sites have been built. Documentation (support information is detailed to parameters and app granularity), CANIUSE tools, and one-code multi-end call examples are provided.

Workflow after Business Connection

After the cross-end API solution is connected, the workflow of the cross-end business is optimized like this:

Centralized Container Capability Information Maintenance: This way, product and development personnel no longer query capabilities one by one but query and evaluate quickly through a unified portal.
SDKs Based on Unified Multi-end Adaptation APIs: This enables development teams to use them directly as a standard API rather than piecing together, debugging, and developing APIs one by one.
Unified SDK maintenance eliminates the workload of testing teams for container capabilities in different models and environments.

Starting from the SDK 1.0 release, the social-networking community (Huiwan) of Xianyu began to pilot and land. The SDK Uni API has been applied to 10+ business units in the Alibaba economy and has gradually become the infrastructure developed at the frontend of the economy.

Outlook

Eliminating differences is not the final destination, the upper-level adaptation to differences is always an intermediate solution, and a set of underlying standard APIs is the optimal solution. The cross-end API call specifications provide input from the upper-layer usage side for the container API standard, which enables new container APIs to be referenced during design and avoids unnecessary differentiation.
The open-source community version was built by the cross-end API team, Rax, and other teams. Currently, the open-source version of the Uni API supports applets and H5 containers from Alibaba, WeChat, Byte Dance, and Baidu. We expect APIs and containers to be continuously expanded in the future.

Community

Uni API: A Unified Cross-End API Solution for Xianyu

Background

Definitions

Scheme Design and Implementation

Overall Design

Specification Formulation

SDK Implementation

Supporting Facilities Construction

Workflow after Business Connection

Outlook

Read previous post:

Read next post:

XianYu Tech

You may also like

Comments

XianYu Tech

Related Products

mPaaS

Super App Solution for Telcos

Mobile Testing

Web Hosting Solution