mirror of
https://github.com/usememos/memos.git
synced 2026-11-19 10:29:11 +01:00
1.7 KiB
1.7 KiB
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.