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 proto/buf.gen.yaml1-31
Protocol Buffer Definition Structure
Code Generation Pipeline
The generated code provides multiple key interfaces for both Go backend and TypeScript frontend:
| Generated File Pattern | Target | Purpose | Key Types |
|---|---|---|---|
*.pb.go | Go | Message definitions and serialization | Memo, User, CreateMemoRequest |
*_grpc.pb.go | Go | gRPC server/client interfaces | MemoServiceServer, UserServiceServer |
*.pb.gw.go | Go | HTTP-to-gRPC translation | RegisterMemoServiceHandlerServer() |
*.connect.go | Go | Connect RPC implementation | MemoServiceClient, MemoServiceHandler |
openapi.yaml | YAML | OpenAPI 3.0 specification | Complete REST API documentation |
*_pb.ts | TS | Frontend type definitions | User, Memo, Visibility |
Sources: proto/buf.gen.yaml1-31 proto/gen/api/v1/memo_service.pb.go1-25 web/src/types/proto/api/v1/user_service_pb.ts1-23 proto/gen/api/v1/memo_service.pb.gw.go1-15
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 |
InstanceService | instance_service.proto | APIV1Service | GetInstanceProfile, BatchGetInstanceSettings |
AttachmentService | attachment_service.proto | APIV1Service | CreateAttachment, ListAttachments |
The MemoService handles the core note-taking logic, while UserService manages identities and settings.
Service Definition Extract (MemoService)
Sources: proto/api/v1/memo_service.proto17-32 proto/api/v1/user_service.proto17-54
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.
| gRPC Method | HTTP Method | Endpoint | Request Body |
|---|---|---|---|
MemoService.CreateMemo | POST | /api/v1/memos | memo field proto/api/v1/memo_service.proto21-27 |
UserService.GetUser | GET | /api/v1/users/{name} | None proto/api/v1/user_service.proto33-36 |
UserService.CreateUser | POST | /api/v1/users | user field proto/api/v1/user_service.proto38-45 |
AIService.Transcribe | POST | /api/v1/ai:transcribe | JSON body proto/gen/openapi.yaml9-33 |
AttachmentService.ListAttachments | GET | /api/v1/attachments | Query params proto/gen/openapi.yaml34-80 |
Sources: proto/api/v1/memo_service.proto17-147 proto/api/v1/user_service.proto17-180 proto/gen/openapi.yaml1-120
The application maintains a single source of truth for public endpoints that do not require authentication. This is defined in acl_config.go.
The PublicMethods map defines endpoints accessible to anonymous users. This includes login, instance profile, and public memos server/router/api/v1/acl_config.go11-41
Public Access Logic
Service-Level Filtering
Even if a method like ListMemos is public, the service layer filters content. For example, ListMemos only returns Visibility_PUBLIC memos for unauthenticated users server/router/api/v1/memo_service.go218-220
Sources: server/router/api/v1/acl_config.go11-81 server/router/api/v1/memo_service.go39-68
The generated gRPC interfaces are implemented by APIV1Service in the server/router/api/v1/ package.
Methods like CreateMemo follow a strict validation and conversion pipeline:
s.fetchCurrentUser(ctx) server/router/api/v1/memo_service.go71-77s.Store.CreateMemo server/router/api/v1/memo_service.go115Sources: server/router/api/v1/memo_service.go70-176 server/router/api/v1/user_service.go55-117
The Memo message represents the core entity. It includes fields for content, visibility, and timestamps.
Sources: proto/gen/api/v1/memo_service.pb.go219-234 proto/api/v1/memo_service.proto150-158
Users are defined with roles (ADMIN, USER) and status proto/gen/api/v1/user_service.pb.go30-38
Sources: proto/gen/api/v1/user_service.pb.go30-52 proto/api/v1/user_service.proto235-245
The API uses standard gRPC status codes. Implementation logic in APIV1Service maps these to appropriate error responses:
| gRPC Status | Use Case |
|---|---|
codes.Unauthenticated | User is not logged in server/router/api/v1/memo_service.go76 |
codes.PermissionDenied | User lacks access to a private memo server/router/api/v1/memo_service.go64 |
codes.InvalidArgument | Invalid filter or content too long server/router/api/v1/memo_service.go106 |
codes.NotFound | Memo or user does not exist server/router/api/v1/memo_service.go41 |
codes.AlreadyExists | Unique constraint violation on Memo UID server/router/api/v1/memo_service.go122 |
Sources: server/router/api/v1/memo_service.go41-125 server/router/api/v1/user_service.go14-15
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.