Evolution of an API Interface Management and Mock Platform at Zhuanzhuan

The API interface documentation platform is a centralized HTTP interface management system designed to be the single source of truth for front‑end and back‑end teams, solving data consistency issues during integration.

Phase 1 : When the business was small (<100 interfaces), interfaces were maintained in a wiki, making search and maintenance cumbersome. The first version introduced a list page and detail page, importing legacy data from the wiki in bulk.

As the number of interfaces grew, additional metadata such as module, class, owner, last modifier, version, and a lock flag for published fields were added.

Phase 2 : To support front‑end and app developers during early development, a mock service was added. Mock routes were selected based on the requester's IP, and mock data were generated with mockjs , providing rich data diversity.

The main issues were the learning curve for editing mockjs data and poor handling of array‑type data, which made editing costly for app developers.

Phase 3 : To simplify editing, the mock implementation switched from mockjs to raw JSON, as illustrated in the following diagram.

The mock workflow now includes:

App sends all HTTP requests to the mock platform; matching rules return mock data, otherwise the request is forwarded.

IP‑based matching binds a requester’s IP to a predefined mock rule.

PC/host scenarios use host file redirection and Nginx reverse‑proxy to route requests to the mock service.

An example of the mobile client using this setup is shown below.

The solution satisfies the app’s data‑mock needs, making configuration and usage straightforward.

Phase 4 : The environment‑setup step still required manually entering both mobile and PC IPs. The proposal is to bind the IP automatically by having the device send a request to the mock platform, thereby eliminating the manual IP entry.

By scanning a QR code, the mobile device and PC can each send a request, allowing the platform to bind the source IP to the mock rule without extra configuration.

Ongoing Iterations : New challenges arose as the number of services and interfaces increased, such as:

Server changes to offline interfaces were not reflected for developers using mock data, causing extra integration time.

Online interface modifications caused downstream errors.

To close this loop, the Beetle platform was integrated:

During branch compilation, Beetle scans the branch’s interfaces and sends them to the API platform for validation against live interfaces; mismatched parameters block the build.

When a branch is released, Beetle notifies the API platform to promote the corresponding interfaces to production.

Real‑time change detection enables automatic notifications to mock users about interface updates.

Editing of interface parameters and data types is disabled on the API platform to prevent manual inconsistencies.

This creates a closed‑loop workflow where interface changes are automatically propagated, eliminating manual intervention.

Note : The server team must follow annotation conventions when exposing interfaces.

In summary, treating the API as a core piece of data and integrating its lifecycle into the DevOps pipeline dramatically reduces communication overhead and error rates as the company scales.