Docs Public APIs

Public APIs

Plumego is intentionally small.

That smallness is protected by a clear rule:

Only APIs explicitly documented as public are stable and supported.

Everything else is internal —
even if it is technically accessible in code.

This document defines what counts as Plumego’s public API surface.

What “Public API” Means in Plumego

A public API in Plumego is an API that:

  • Is documented in the Reference section
  • Is intended for application authors
  • Carries backward-compatibility guarantees
  • Can be relied upon across minor releases

If an API is not documented here, it is not public.

Why This Distinction Matters

Without a clear public surface:

  • Users depend on internals accidentally
  • Refactoring becomes impossible
  • Bugs become “features”
  • Framework evolution stalls

Plumego avoids this by being explicit about support boundaries.

Categories of Public APIs

Plumego public APIs fall into a small number of categories.

1. Application-Level APIs

These are used to construct and wire a Plumego application.

Examples include:

  • Application creation
  • Middleware registration
  • Route registration
  • Grouping

These APIs define how a Plumego app is assembled.

(See Reference / App for exact signatures.)

2. Context APIs

These APIs are available on the request-scoped Context.

They allow handlers and middleware to:

  • Access the request
  • Write responses
  • Store request-scoped metadata
  • Read route parameters

Context APIs are among the most stable in Plumego.

(See Reference / Context.)

3. Routing APIs

Routing APIs allow applications to:

  • Register routes
  • Bind HTTP methods
  • Define route groups
  • Apply scoped middleware

Routing APIs are explicit and deterministic by design.

(See Reference / Router.)

4. Middleware APIs

Middleware APIs define:

  • Middleware function signatures
  • Registration order
  • Execution semantics

These APIs are tightly constrained and stable.

(See Reference / Middleware and Middleware Signatures.)

5. Handler APIs

Handlers define the boundary between HTTP and application logic.

Public aspects include:

  • Handler function signatures
  • How handlers receive Context
  • How handlers terminate execution

Handlers do not return values.
Response writing is explicit.

(See Reference / Handler.)

6. Response Helper APIs

Plumego may expose small helper methods such as:

  • JSON
  • Text
  • Status

These helpers are:

  • Convenience APIs
  • Thin wrappers
  • Fully optional

Their behavior is documented and stable,
but they do not define new semantics.

(See Reference / Response.)

APIs That Are Not Public

The following are explicitly not public APIs.

Internal Types and Packages

Anything under:

  • internal/
  • undocumented subpackages
  • implementation-specific files

Is subject to change without notice.

Execution Internals

This includes:

  • Router implementation details
  • Middleware chaining internals
  • Context storage internals
  • Dispatch algorithms

You may read them, but you must not rely on them.

Implicit or Emergent Behavior

If behavior is:

  • Not documented
  • Only observable indirectly
  • Not guaranteed explicitly

It is not a public API.

Backward Compatibility Guarantees

For public APIs, Plumego guarantees:

  • No breaking changes within a major version
  • Deprecations are documented before removal
  • Breaking changes require a major version bump

For non-public APIs, no guarantees exist.

How to Tell If an API Is Public

Ask these questions:

  1. Is it documented in Reference?
  2. Is it described as stable?
  3. Is it intended for application authors?

If any answer is “no”, treat it as internal.

Public APIs and Versioning

Public APIs are versioned as a set, not individually.

This means:

  • Adding new public APIs is backward compatible
  • Changing existing public APIs is not
  • Removing public APIs requires a major version bump

This keeps versioning understandable and predictable.

Designing Code Against Public APIs

When building on Plumego:

  • Depend only on documented APIs
  • Avoid importing internal packages
  • Avoid copying internal patterns blindly
  • Prefer explicit wiring over introspection

If you feel tempted to reach into internals,
that is a signal to revisit architecture.

Testing Against Public APIs

Tests should:

  • Use only public APIs
  • Avoid asserting on internal behavior
  • Treat internals as opaque

This ensures tests survive framework upgrades.

Summary

In Plumego:

  • Public APIs are explicitly documented
  • Everything else is internal
  • Stability applies only to the documented surface
  • Clear boundaries enable evolution

If an API matters, it is documented.
If it is not documented, it is not a promise.

  • App — application-level public APIs
  • Context — request-scoped APIs
  • Router — routing APIs
  • Middleware Signatures — middleware contracts

This page defines Plumego’s support boundary —
and that boundary is what keeps the framework healthy long-term.