gram-management-api

Gram's management API is the internal HTTP-RPC surface that the dashboard, CLI, and SDK use to administer projects, toolsets, deployments, access, and related resources. Every endpoint lives at /rpc/<service>.<method>, is authored in Goa DSL under server/design/, implemented in a single Service struct per package under server/internal/<service>/, and exposed through generated server stubs, OpenAPI, CLI bindings, and a TypeScript SDK.

Concepts and terminology

Service. A named collection of related endpoints (e.g. remoteMcp, access, auditlogs). Each service maps one-to-one to a Go package of the same name.

Method. A single endpoint on a service. Exposed as /rpc/<service>.<method>.

Payload / Result. The input and output types for a method. Payloads are composed from shared security payloads plus method-specific form attributes.

Security scheme. The authentication mechanism a method accepts. Gram's management endpoints use three schemes: Session (browser cookie), ByKey (API key header), and ProjectSlug (project-selector header). Additional schemes exist for non-management surfaces and are out of scope here.

Model views (mv). Stateless functions that convert database row types into API response types. Keep database types out of the API boundary — handlers always return a view, never a repo struct.

Handler. One method implementation on the Service struct.

Management API vs public SDK. The same Goa design produces two OpenAPI outputs: an internal spec used to generate the TypeScript SDK that powers the dashboard and CLI, and a public spec derived from it via redaction overlays. Only the internal SDK sees every endpoint.

Changeset. A short changelog file written alongside a change that identifies which package bumps (server, dashboard, sdk) and by how much (patch, minor, major).