mirror of
https://github.com/usememos/memos.git
synced 2026-11-19 10:29:11 +01:00
Memos API Design
This API design should follow the guidelines and best practices outlined in the Google API Improvement Proposals (AIPs).
The package is memos.api. It carries no version marker; breaking changes are recorded in CHANGELOG.md.
File Layout
- The service, then shared top-level types used by more than one group.
- One block per resource group, in service order: the resource message, then the group's request/response messages in RPC order, then helper messages used only by that group.
Within a group, order RPCs List, Get, BatchGet, Create, Update, Delete, BatchDelete, then custom methods.
Messages
- Resources:
namefirst, timestamps (create_time,update_time, others) last. - Requests:
parentorname, the payload,update_mask, thenpage_size,page_token,filter,order_by, and other options. - Responses: items, then
next_page_token. - Fields first, then nested enums, then nested messages.
- Number fields 1..N in declaration order. A new field takes the next number; never reuse or renumber a released field outside a recorded breaking change.
google.api.resourceliststype,pattern,singular,plural; omitname_field: "name".
Comments
- Every service, RPC, message, enum and field has a comment. RPC comments start with the RPC name.
- Fields with
google.api.field_behaviorstart with the matching prefix:Identifier.,Required.,Optional.,Output only., orInput only.. Fields without the annotation get no prefix. - Resource-name fields end with a
Format: memos/{memo}line. - Describe what the server does, not what it might do.