This document covers the API architecture, protocol definitions, and service interfaces for the memos application. It focuses on the Protocol Buffer schema definitions, gRPC services, and their HTTP/REST mappings that form the core API layer.
For backend service implementations, see Backend. For client-side API usage patterns, see Frontend.
The memos application uses Protocol Buffers as the single source of truth for all API definitions. Proto files define gRPC services that are automatically exposed as both native gRPC endpoints and HTTP/REST APIs through grpc-gateway. The build system uses buf for linting and code generation.
Protocol Buffer Definition Structure
Code Generation Pipeline
The generated code provides three key interfaces:
| Generated File Pattern | Purpose | Key Types |
|---|---|---|
*.pb.go | Message definitions and serialization | Memo, User, CreateMemoRequest, ListMemosResponse |
*_grpc.pb.go | gRPC server/client interfaces | MemoServiceServer, MemoServiceClient |
*.pb.gw.go | HTTP-to-gRPC translation | RegisterMemoServiceHandlerServer() |
Sources: proto/api/v1/memo_service.proto1-512 proto/gen/api/v1/memo_service.pb.go1-27 proto/gen/api/v1/memo_service_grpc.pb.go1-644 proto/gen/api/v1/memo_service.pb.gw.go1-1100
Code Generation Pipeline
The generated code provides three key interfaces:
| Generated File Pattern | Purpose | Key Types |
|---|---|---|
*.pb.go | Message definitions and serialization | Memo, User, CreateMemoRequest, ListMemosResponse |
*_grpc.pb.go | gRPC server/client interfaces | MemoServiceServer, MemoServiceClient |
*.pb.gw.go | HTTP-to-gRPC translation | RegisterMemoServiceHandlerServer() |
openapi.yaml | OpenAPI 3.0 specification | Complete REST API documentation |
Sources: proto/api/v1/memo_service.proto1-512 proto/gen/api/v1/memo_service.pb.go1-2600 proto/gen/api/v1/memo_service_grpc.pb.go1-644 proto/gen/api/v1/memo_service.pb.gw.go1-1100
The API layer consists of multiple gRPC services defined in proto files under proto/api/v1/. Each service defines a cohesive set of operations for a specific domain.
| Service | Proto File | Implementation | Key RPCs |
|---|---|---|---|
MemoService | memo_service.proto | APIV1Service | CreateMemo, ListMemos, UpdateMemo |
UserService | user_service.proto | APIV1Service | CreateUser, GetUser, UpdateUser |
AuthService | auth_service.proto | APIV1Service | SignIn, SignOut, RefreshToken |
AttachmentService | attachment_service.proto | APIV1Service | CreateAttachment, ListAttachments |
MemoService RPC Interface
Service Definition Extract
Sources: proto/api/v1/memo_service.proto17-106 proto/gen/api/v1/memo_service_grpc.pb.go22-253
UserService RPC Methods Overview
The UserService provides comprehensive user management functionality including CRUD operations, settings management, personal access tokens, and webhook configuration.
| RPC Method | Request Type | Response Type |
|---|---|---|
CreateUser | CreateUserRequest | User |
GetUser | GetUserRequest | User |
UpdateUser | UpdateUserRequest | User |
DeleteUser | DeleteUserRequest | Empty |
ListUsers | ListUsersRequest | ListUsersResponse |
GetUserSetting | GetUserSettingRequest | UserSetting |
UpdateUserSetting | UpdateUserSettingRequest | UserSetting |
CreatePersonalAccessToken | CreatePersonalAccessTokenRequest | PersonalAccessToken |
DeletePersonalAccessToken | DeletePersonalAccessTokenRequest | Empty |
CreateUserWebhook | CreateUserWebhookRequest | UserWebhook |
UpdateUserWebhook | UpdateUserWebhookRequest | UserWebhook |
DeleteUserWebhook | DeleteUserWebhookRequest | Empty |
Sources: proto/api/v1/user_service.proto16-159
The gRPC services are automatically exposed as RESTful HTTP endpoints through grpc-gateway. Each RPC method has HTTP annotations in the proto file that define its REST mapping.
Proto HTTP Annotations
| gRPC Method | HTTP Method | Endpoint | Request Body |
|---|---|---|---|
MemoService.CreateMemo | POST | /api/v1/memos | memo field |
MemoService.ListMemos | GET | /api/v1/memos?page_size=10&filter=... | Query params |
MemoService.GetMemo | GET | /api/v1/memos/{memo} | Path param |
MemoService.UpdateMemo | PATCH | /api/v1/memos/{memo} | memo field + update_mask |
MemoService.DeleteMemo | DELETE | /api/v1/memos/{memo} | None |
UserService.CreateUser | POST | /api/v1/users | user field |
UserService.GetUser | GET | /api/v1/users/{user} | Path param |
UserService.ListUsers | GET | /api/v1/users?filter=username=="alice" | Query params |
Sources: proto/api/v1/memo_service.proto18-106 proto/api/v1/user_service.proto16-159
HTTP to gRPC Translation Flow
The generated gateway code in *.pb.gw.go files handles:
Sources: proto/gen/api/v1/memo_service.pb.gw.go38-77 server/router/api/v1/memo_service.go24-145
The proto definitions can be configured to generate OpenAPI 3.0 specifications that document all REST endpoints, request/response schemas, and parameter details. The generated specification provides comprehensive API documentation for REST clients.
Key OpenAPI Components Generated:
The OpenAPI generation is handled by protoc-gen-openapiv2 or protoc-gen-openapi during the build process, converting the proto annotations into a complete API specification.
Sources: proto/api/v1/memo_service.proto7-11
The generated gRPC interfaces are implemented by APIV1Service in the server/router/api/v1/ package.
Service Implementation Structure
CreateMemo Implementation Flow
The CreateMemo RPC handler in memo_service.go:
Sources: server/router/api/v1/memo_service.go24-145
Resource Name Extraction Helpers
The service layer provides utility functions to parse resource names and extract identifiers:
| Function | Input Example | Output |
|---|---|---|
ExtractMemoUIDFromName(name) | "memos/abc123" | "abc123" |
ExtractUserIDFromName(name) | "users/101" | 101 |
These functions validate the resource name format and extract the identifier portion for database queries.
Sources: server/router/api/v1/memo_service.go290-292 server/router/api/v1/memo_service.go338-341
The proto definitions establish strongly-typed data structures with field behaviors that control how they're processed.
Memo Message Structure
Field Behavior Annotations
| Behavior | Meaning | Example Fields |
|---|---|---|
REQUIRED | Must be provided in requests | content, visibility |
OPTIONAL | May be omitted | pinned, location, display_time |
OUTPUT_ONLY | Server-generated, ignored in requests | create_time, creator, tags, reactions |
IDENTIFIER | Resource identifier field | name |
INPUT_ONLY | Only used in requests, not in responses | password in User |
Sources: proto/api/v1/memo_service.proto153-231
User Message Structure
Sources: proto/api/v1/user_service.proto161-220
MemoPayload Structure
The MemoPayload message stores computed metadata derived from memo content:
The payload is serialized to JSON and stored in the database payload column. It's populated by memopayload.RebuildMemoPayload() during memo creation and updates.
Sources: proto/store/memo.proto1-30
Visibility Enum
State Enum (common.proto)
Sources: proto/api/v1/memo_service.proto108-113 proto/gen/api/v1/memo_service.pb.go28-78
List operations follow Google AIP-158 pagination patterns with page_size and page_token:
ListMemosRequest Definition
Pagination Implementation
The service implementation in memo_service.go handles pagination:
Sources: proto/api/v1/memo_service.proto253-291 server/router/api/v1/memo_service.go147-286
Update operations use google.protobuf.FieldMask to specify which fields to update:
UpdateMemoRequest Definition
Field Mask Processing
The service processes the update mask to apply only specified fields:
Sources: proto/api/v1/memo_service.proto302-309 server/router/api/v1/memo_service.go337-475
List operations support Common Expression Language (CEL) filters:
Filter Examples
creator_id == 5 - Memos by specific uservisibility == "PUBLIC" - Only public memoscreator_id == 5 || visibility in ["PUBLIC", "PROTECTED"] - User's memos or accessible memoshas_link == true - Memos containing linkshas_incomplete_tasks == true - Memos with incomplete tasksFilter Processing
Filters are parsed by the CEL engine and converted to SQL WHERE clauses:
Sources: proto/api/v1/memo_service.proto275-278 server/router/api/v1/memo_service.go170-175 store/db/sqlite/memo.go54-63
All resources follow the pattern {collection}/{identifier}:
| Resource Type | Name Pattern | Example |
|---|---|---|
| Memo | memos/{memo} | memos/abc123 |
| User | users/{user} | users/101 or users/alice |
| Attachment | attachments/{attachment} | attachments/xyz789 |
| Reaction | memos/{memo}/reactions/{reaction} | memos/abc/reactions/1 |
| User Setting | users/{user}/settings/{setting} | users/101/settings/general |
| Access Token | users/{user}/personalAccessTokens/{token} | users/101/personalAccessTokens/tok_xyz |
Sources: proto/api/v1/memo_service.proto154-164
The API uses standard gRPC status codes that map to HTTP status codes:
| gRPC Status | HTTP Code | Usage |
|---|---|---|
OK | 200 | Successful operation |
INVALID_ARGUMENT | 400 | Invalid request parameters |
UNAUTHENTICATED | 401 | Missing or invalid authentication |
PERMISSION_DENIED | 403 | Insufficient permissions |
NOT_FOUND | 404 | Resource not found |
INTERNAL | 500 | Server-side errors |
Error responses include structured error details with context-specific messages for debugging and user feedback.
Sources: server/router/api/v1/memo_service.go32-33 server/router/api/v1/user_service.go32-35
Refresh this wiki