API Management and Standardization at Bilibili: Design, Automation, Versioning, and Mocking

API management is an essential part of application development. When the number of services is small, teams can handle API management themselves, but as the company grows and the number of business interfaces explodes, a unified API management platform becomes necessary to avoid fragmented practices and reduce cross‑department communication costs.

The current platform at Bilibili manages over 120,000 online interfaces and nearly 20,000 applications, saving significant manpower and aligning with the company’s cost‑reduction goals.

01 Service Launch Process

The typical service launch includes:

1. Requirement review and analysis – PM defines requirements, PMO organizes review, developers estimate effort and set iteration cycles.

2. Writing and maintaining API documentation – Front‑end and back‑end developers jointly define interfaces, create documentation early, and keep it updated throughout the project.

3. Front‑end and back‑end integration testing – Front‑end implements based on the docs, back‑end publishes to a test environment for integration.

4. Release – Once ready, the service is deployed online and the API becomes publicly available.

A well‑maintained API document improves collaboration, onboarding, and testing efficiency.

02 API Management

Unified management is needed because different teams previously used disparate documentation methods (knowledge bases, Swagger in version control, etc.), leading to inefficiencies and delayed detection of API issues.

2.1 Manual Maintenance

Bilibili once deployed a private YAPI instance that required developers to manually enter interface details. This approach suffered from high labor cost, untimely information synchronization, and error‑prone updates.

2.2 Automatic Generation

The platform now automatically collects API metadata and generates accurate documentation, allowing developers to focus on API design. The architecture follows a standard API definition, packaging, and automatic collection pipeline.

For Go developers, interfaces are defined in Protobuf IDL. Example:

// Demo service responds to incoming requests.
service DemoService {
  option (google.api.default_host) = "api.example.com";
  // DemoBody method receives a simple message and returns it.
  rpc DemoBody(SimpleMessage) returns (SimpleMessage) {
    option (google.api.http) = {
      post: "/poc/probe/demo_body"
      body: "*"
    };
  }
}

message SimpleMessage {
  int32 id = 1 [(google.api.field_behavior) = REQUIRED];
  Embedded embedded = 2;
}

message Embedded {
  int64 int64_val = 1 [(gogoproto.moretags) = 'default:"1"'];
  string string_val = 2;
  // 一个字符串列表
  repeated string repeated_string_val = 3;
  // 一个字符串Map
  map
map_string_val = 4;
}

This snippet defines a gRPC service with an HTTP POST mapping, following Google’s API best practices and Bilibili’s Kratos V2 framework.

For Java developers, Swagger annotations are used to generate OpenAPI documentation automatically:

@GetMapping("/demo")
@Operation(summary = "用户接口 - debug", description = "示例")
@Parameter(name = "count", required = false)
public String debug(@RequestParam(defaultValue = "128", required = false) int count) {
    String randomString = RandomStringUtils.randomAlphabetic(count);
    LOGGER.debug(randomString);
    return randomString;
}

The platform collects documentation via CI pipelines (using protoc‑gen‑bilibili‑openapi) and by calling /api‑docs on deployed services, ensuring both Go and Java services are kept up‑to‑date without manual effort.

03 Version Management

API versioning ties each interface version to a specific code commit (Commit ID) and distinguishes between test versions (linked to a dev branch commit) and production versions (linked to a tag on the main branch). This enables automatic diffing, validation, and safe rollout of changes.

Application version management treats an application as a collection of interface versions. Snapshots of interface sets represent application versions, allowing stakeholders to see which APIs are used by each version and track lifecycle changes.

04 Collaboration, Sharing, and Debugging

The platform integrates with API Gateway, supports exporting OpenAPI JSON, and provides unified debugging for both HTTP and gRPC interfaces, abstracting protocol differences from users.

05 Mocking

Mocking creates virtual responses during development and testing, reducing front‑end/back‑end coupling and improving test coverage. Bilibili’s service‑level mock architecture injects mock instances via the service registry, routing traffic to mock services when rules match, while unmocked traffic is forwarded to the real service.

06 Microservice Standardization

Bilibili standardizes microservices using Go (Kratos) and Java (Pleiades/Kraten) frameworks, embedding OpenAPI generation into build and CI stages. This standardization enables consistent monitoring, code generation, and further automation.

References:

[1] Kratos API component – https://go-kratos.dev/docs/component/api/

[2] Google API Design Guide – https://google-cloud.gitbook.io/api-design-guide/custom_methods

[3] API version control importance – http://blog.eolinker.com/?p=2644

[4] Mock testing overview – https://www.51cto.com/article/647732.html