gRPC & REST APIs
Relevant source files
The following files were used as context for generating this wiki page:
Percona Monitoring and Management (PMM) utilizes a dual-layered API architecture consisting of gRPC for internal service-to-service communication and a RESTful interface for client-facing integrations. The REST API is dynamically generated from gRPC service definitions using the grpc-gateway toolset, ensuring consistency between both interfaces.
The API serves as the primary gateway for PMM Server components, including pmm-managed and qan-api, enabling management of database configurations, user accounts, and monitoring agents.
Sources: CONTRIBUTING.md:27-38, api/README.md:1-5
API Architecture and Generation
The PMM API lifecycle begins with .proto files, which define the service contracts. These definitions are processed to generate Go code for gRPC servers, Swagger (OpenAPI v2) specifications for documentation, and gateway code for REST translation.
Development Workflow
Developers modify only the .proto files and use a centralized build system to update the generated artifacts.
The diagram shows the transition from Protocol Buffer definitions to functional gRPC and REST endpoints.
Sources: api/README.md:9-25, CONTRIBUTING.md:94-100
User Service API Implementation
The UserService serves as a practical example of the API structure, exposing RPCs for user management that are mapped to standard HTTP verbs (GET, PUT).
Service Definition
The service utilizes google.api.http options to define the mapping between gRPC methods and REST paths.
service UserService {
rpc GetUser(GetUserRequest) returns (GetUserResponse) {
option (google.api.http) = {get: "/v1/users/me"};
}
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (google.api.http) = {
put: "/v1/users/me"
body: "*"
};
}
}
Sources: api/user/v1/user.proto:65-80
Endpoint Summary
The following table describes the REST endpoints exposed by the User Service based on the Swagger definition:
| Method | Path | Summary | Description |
|---|---|---|---|
| GET | /v1/users | List all users | Retrieve details for all PMM users |
| GET | /v1/users/me | Get user details | Retrieve current user profile |
| PUT | /v1/users/me | Update a user | Update settings like tour completion or version alerts |
Sources: api/user/v1/user.swagger.json:19-75
Data Structures and Models
API requests and responses are strongly typed. Key fields often include metadata regarding UI state (e.g., tours) and PMM versioning information.
User Model Fields
| Field | Type | Description |
|---|---|---|
user_id | uint32 | Unique identifier for the user |
product_tour_completed | bool | Status of the product onboarding tour |
alerting_tour_completed | bool | Status of the alerting onboarding tour |
snoozed_pmm_version | string | Version for which updates have been snoozed |
snooze_count | uint32 | Frequency of update alert dismissals |
Sources: api/user/v1/user.proto:15-30, api/user/v1/user.swagger.json:144-180
Authentication and Security
The PMM API supports Basic Authentication for development and testing. Security definitions are centralized in Swagger headers, specifying supported schemes and required authorization.
Security Configuration
The development API header enforces HTTPS/HTTP schemes with a basicAuth requirement for all operations.
{
"securityDefinitions": {
"basicAuth": {
"type": "basic"
}
},
"security": [
{
"basicAuth": []
}
]
}
Sources: api/swagger/header-dev.json:12-22, api/swagger/header.json:10-18
Component Interactions
The APIs act as the interface between PMM Server backends and various clients.
This diagram illustrates how administrative tools interact with the PMM Server backend through the API layer.
Sources: CONTRIBUTING.md:30-45, managed/CONTRIBUTING.md:124-135
Conclusion
The gRPC and REST APIs provide a unified and consistent interface for managing Percona Monitoring and Management. By leveraging Protocol Buffers and the gRPC-Gateway, PMM ensures that internal high-performance communication and external web-based integrations remain synchronized and well-documented.