RFC-0033 · API Service Declaration
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
The existing I/O RFC suite (RFC-0024 through RFC-0031) defines how Gnomon modules act as clients — calling external services over HTTP, gRPC, tRPC, GraphQL, and Protobuf. This covers one direction of the API surface. The symmetric direction — how an Gnomon module exposes its own operations for external callers — has no corresponding model.
This RFC introduces the api declaration: the protocol-agnostic public service surface of an Gnomon module. An api declaration answers the question “what can you call on this module?” without specifying how those calls are transmitted over the wire. Protocol-specific binding rules (route tables, gRPC service names, handler stub generation) are defined in RFC-0034.
The design principle is the same one established by the I/O adapter model: the language owns the protocol-agnostic contract; protocol modules own the wire mapping.
2. Relationship to Existing Concepts
| Concept | Direction | Contract owner |
|---|---|---|
client (RFC-0024) | Outbound — this module calls an external service | External spec or author-declared operations |
api (this RFC) | Inbound — external callers invoke this module | This module |
app (RFC-0008 §6.x) | UI surface — renders module state in a browser or native app | This module |
An api is not a UI surface. It exposes programmatic operations (action, query, procedure) for machine callers. An app renders the same domain model for human callers via a component tree. A module MAY declare both.
The following table illustrates the full client/server symmetry this RFC establishes alongside RFC-0034:
| Client side | Server side |
|---|---|
client declaration (RFC-0024) | api declaration (this RFC) |
operation {} slot | exposed operation reference in exposes {} |
Protocol adapter extends operation {} (RFC-0025–0031) | Protocol adapter extends serve-operation {} (RFC-0034) |
| Compiler generates typed call stubs | Compiler generates typed handler stubs |
3. Definitions
apideclaration: A named, protocol-agnostic declaration that enumerates which of this module’saction,query, andproceduredeclarations are publicly callable by external systems.- exposed operation: An
action,query, orprocedurelisted in anapideclaration’sexposesblock. - auth scheme: A declared authentication mechanism callers must satisfy to invoke any operation in this
api. - server binding (RFC-0034): A
servedeclaration that maps anapi’s exposed operations to wire protocol endpoints (HTTP routes, gRPC methods, tRPC procedures, GraphQL operations). - handler stub: A compiler-generated typed entry point for a single exposed operation, produced by the server binding (RFC-0034 §7).
4. Invariants
- An
apiMUST reference onlyaction,query, andproceduredeclarations that are declared in the same module or imported from a declared dependency. Unresolved references MUST produce error M33006. - An
apiMUST NOT exposemutation,task,actuator,saga, orworkflowdeclarations directly. These are internal execution primitives; they MUST be exposed only through wrappingactionorproceduredeclarations. - An
apiMUST NOT exposeagentorpolicydeclarations. AI participation contracts and policy constraints are internal governance, not public API surface. - An
apiMUST declare at least one operation in itsexposesblock. An emptyexposesblock MUST produce error M33001. - An
api’sversionfield MUST be a valid semantic version string (MAJOR.MINOR.PATCH per SemVer 2.0.0). Malformed version strings MUST produce error M33002. - Auth scheme identifiers in the
auth.schemeslist MUST be recognized values (§6.3). Unrecognized identifiers MUST produce error M33003. - Error types listed in the
errors.commonblock MUST resolve to declaredentityorvarianttypes in scope. Unresolved references MUST produce error M33004. - The scheme
noneMUST NOT be listed alongside other schemes in the sameauthblock. Combiningnonewith any other scheme MUST produce error M33005. - A module MAY declare multiple
apideclarations representing distinct versioned or audience-specific surfaces. The same operation MAY appear in more than oneapideclaration. - An
apiMUST NOT expose a declaration markedinternal. Attempting to do so MUST produce error M33007. - A
stableapiMUST NOT expose adraftorexperimentaloperation. Violations MUST produce error M33008.
5. Declaration Syntax
api-decl ::=
[epistemic-modifier]
"api" IDENT "{" api-body "}"
epistemic-modifier ::= "draft" | "experimental" | "stable"
api-body ::=
meaning-slot
["version" ":" STRING]
exposes-block
[auth-block]
[errors-block]
[deprecated-block]
exposes-block ::=
"exposes" "{" expose-entry* "}"
expose-entry ::=
expose-kind "[" IDENT ("," IDENT)* "]"
expose-kind ::= "actions" | "queries" | "procedures"
auth-block ::=
"auth" "{" auth-entry* "}"
auth-entry ::=
"required" ":" BOOL
| "schemes" "[" auth-scheme ("," auth-scheme)* "]"
auth-scheme ::=
"bearer-token" | "api-key" | "basic" | "mutual-tls" | "none"
errors-block ::=
"errors" "{" "common" "[" IDENT ("," IDENT)* "]" "}"
deprecated-block ::=
"deprecated" "{" "reason" ":" STRING ["since" ":" STRING] "}"
6. Semantics
6.1 exposes Block
The exposes block is the normative roster of operations this api makes callable. Only operations listed here are externally reachable.
actions— references toactiondeclarations.queries— references toquerydeclarations.procedures— references toproceduredeclarations.
All three sub-lists are optional within the block, but at least one entry across all three MUST be present (Invariant 4). Operations NOT listed in exposes are internal to the module. The compiler MUST NOT emit routing metadata or handler stubs for unlisted operations.
6.2 version Field
The version field declares the API version. This value:
- MAY be used by protocol bindings (RFC-0034) to construct versioned URL paths (e.g.,
/api/v1/) orContent-Typeversion headers. - Is included in the compiled bundle and is diffable across module versions.
- MUST be incremented according to RFC-0014 semantic versioning rules when breaking changes are made to any exposed operation’s input or output contract.
If version is omitted, the compiler uses the module version from module.gnm as a default.
6.3 auth Block
The auth block declares authentication requirements for all operations in this api:
required: true— every caller MUST authenticate. Unauthenticated requests MUST be rejected by the runtime before any operation handler is invoked. This is the default whenauthis omitted.required: false— the API accepts unauthenticated callers. Individual operations MAY still enforce authorization internally viapolicydeclarations.schemes— the set of authentication mechanisms the API will accept. At runtime, a caller using any listed scheme is considered authenticated. Order implies preference (first = most preferred) but does not restrict callers.
Recognized scheme values:
| Scheme | Wire form |
|---|---|
bearer-token | Authorization: Bearer <token> |
api-key | X-Api-Key: <key> header (or ?apiKey=<key> query parameter) |
basic | Authorization: Basic <base64> |
mutual-tls | Client certificate presented at TLS handshake |
none | No authentication; MUST be declared alone (Invariant 8) |
6.4 errors.common Block
The errors.common list declares error types that any operation in this api may return regardless of what the individual operation’s errors {} block declares. These are typically infrastructure-level errors shared across the service surface:
NotFound— the requested resource does not existUnauthorized— the caller is not authenticated or lacks the required scopeRateLimitExceeded— the caller has exceeded their rate limitServiceUnavailable— a transient infrastructure failure
These types MUST be declared entity or variant types in scope. The compiler injects them into the error taxonomy of every exposed operation’s generated handler stub. Operations that already declare a matching error type are not duplicated.
6.5 procedure vs action as Public Surface
An exposed procedure is the preferred entry point for state-changing operations. A procedure wraps an action, enforces the typed input/output contract, and has a bounded error surface. Exposing raw action declarations is permitted but SHOULD be accompanied by a lint warning (M33010) because actions are lower-level execution primitives whose error taxonomy is less constrained.
Exposed query declarations are read-only by definition and are the correct choice for data-retrieval endpoints.
7. Example
// modules/selectsmart/benefits/api.gnm
import "gnomon.errors"
stable api BenefitsAPI {
meaning: "SelectSmart benefits management API — exposed to employer portals and benefits admin tools."
version: "1.2.0"
exposes {
actions [enrollInPlan, changeElection, terminateCoverage]
queries [getEnrollmentStatus, listAvailablePlans, getHouseholdSummary]
procedures [submitEnrollment, amendElection]
}
auth {
required: true
schemes [bearer-token, api-key]
}
errors {
common [
gnomon.errors.NotFound,
gnomon.errors.Unauthorized,
gnomon.errors.ValidationError,
gnomon.errors.RateLimitExceeded
]
}
}
draft api BenefitsAdminAPI {
meaning: "Internal admin surface for plan year management — not exposed to external callers."
version: "0.1.0"
exposes {
actions [archivePlanYear, recalculateEligibility]
queries [listPlanYears, getPlanYearSummary]
}
auth {
required: true
schemes [mutual-tls]
}
}
8. Declaration Class and File Naming
api is an Operations-class declaration (RFC-0008 §3), alongside action, query, and serve. It MUST be declared in a file named api.gnm within a concept folder. Placing an api declaration in any other file class MUST produce error M08701 (mixed declaration classes).
The api.gnm predefined filename is added to RFC-0001’s predefined file table. The compiler auto-discovers api.gnm under the folder convention; no explicit listing in module.gnm is required.
9. Compiler Validation
- Every reference in
exposes.actions,exposes.queries, andexposes.proceduresMUST resolve to a declared operation of the stated kind in the current module or an imported dependency. Mismatched kinds (e.g., aqueryreferenced underactions) MUST produce error M33006. - An
apithat exposes aninternaldeclaration MUST produce error M33007. - A
stableapithat exposes adraftorexperimentaloperation MUST produce error M33008 (supersedes the general M08780 for this context). - The compiler MUST verify that every operation referenced in
exposeshas no unresolved types in itsinput {}orreturnsdeclaration. An exposed operation with unresolved input or output types MUST produce error M33006 (cannot expose an operation with an incomplete contract). - Two
apideclarations in the same module with the sameversionstring MUST produce warning M33009. - An
apithat exposes a rawaction(rather than aprocedure) MUST produce warning M33010 advising the author to wrap it in aprocedurefor public surface.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
11. Diagnostic Codes (M33xxx)
All diagnostics introduced by this RFC occupy the M33000–M33999 range.
M330x: Declaration structure
- M33001:
apideclarationexposesblock is empty — at least one operation MUST be listed (error) - M33002:
apiversionfield is not a valid semantic version string (MAJOR.MINOR.PATCH) (error) - M33003: Unrecognized auth scheme identifier in
auth.schemes(error) - M33004:
errors.commonentry references an unresolved type — must be a declared entity or variant in scope (error) - M33005:
noneauth scheme combined with other schemes in the sameauthblock (error) - M33006: Operation reference in
exposesis unresolved or resolves to the wrong declaration kind (error) - M33007:
apiexposes a declaration markedinternal— internal declarations MUST NOT appear in public API surface (error) - M33008:
stableapiexposes adraftorexperimentaloperation (error) - M33009: Two
apideclarations in the same module share the sameversionstring (warning) - M33010:
apiexposes a rawaction— prefer wrapping in aprocedurefor a well-bounded public surface (warning)
M331x: Version and compatibility
- M33100:
apiversionstring is lower than the previously published version for this module (error — cannot publish a lower API version) - M33101: Exposed operation input or output contract changed in a way inconsistent with the declared version bump (error — breaking changes require a MAJOR increment per RFC-0014)