Bilibili’s API Management Design and Practices

API management is essential for modern application development, and as the number of services grows, Bilibili has moved from ad‑hoc documentation to a unified platform that centralizes API metadata, reduces inter‑team communication overhead, and supports large‑scale interface governance.

Service launch process

The typical workflow includes requirement review, API documentation authoring, front‑back integration testing, and finally publishing the service online. Throughout these stages, well‑maintained API docs are crucial for efficient collaboration.

Why a unified API platform?

Without a central system, teams use disparate tools (knowledge bases, Swagger, version control) leading to inconsistent documentation, delayed issue detection, and version‑control challenges. A unified platform standardizes collection, synchronization, and notification of API changes.

Metadata collection

Initially Bilibili used a private YAPI instance for manual entry, which suffered from high labor cost and untimely updates. The platform now supports automatic generation: developers define APIs in code, and the system extracts metadata during CI pipelines.

For Go services, APIs are defined using protobuf with Google annotations, e.g.:

// Demo service responds to incoming requests.
service DemoService {
option (google.api.default_host) = "api.example.com";
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_string_val = 4;
}

For Java services, Swagger annotations generate OpenAPI definitions 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 these definitions, generates OpenAPI JSON, and makes them available via /api-docs endpoints for downstream consumption.

Version management

API versions are tied to code commits (for test versions) or tags (for production versions). Each commit triggers a new API version, enabling developers to compare changes, perform automated testing, and share stable versions with consumers.

Application versions are snapshots of a set of API versions, allowing callers to see which interfaces are available in a particular release.

Collaboration, sharing, and debugging

The platform integrates with API Gateway, supports OpenAPI export, and provides unified debugging for both HTTP and gRPC services, abstracting away protocol details from users.

Mock testing

Mock services generate virtual responses during development, reducing front‑back dependency delays. Bilibili’s mock architecture injects mock instances via the service registry, routing traffic to mock or real services based on configurable rules.

Micro‑service standardization

Using Go’s Kratos framework and Java’s Pleiades/Kraten framework, Bilibili enforces consistent API definitions, data formats, and documentation generation, turning API metadata into a productivity tool for monitoring, code generation, and more.

References:

Kratos API definition guide

Google API Design Guide

EOLINKER blog on API version control

51CTO article on mock testing