x/rest Primer

x/rest Primer

Beta — API is stable within a minor version. Check Release Posture and Extension Maturity before adopting in production.

Open this page after x/* Family when the change is clearly about reusable resource-interface behavior rather than the smallest canonical service shape.

x/rest is Plumego’s app-facing reusable resource-interface layer for CRUD route standardization, query parsing, pagination rules, and repository-backed resource wiring.

Stability and adoption

x/rest is an extension surface, not part of the smallest stable-root path. Check x/rest/module.yaml, Release Posture, and Extension Maturity before using it in a production path. If compatibility matters, wrap it behind application-local controllers or interfaces.

Start here when

• the task is standardizing reusable resource APIs
• the change is controller-level CRUD transport behavior
• the work is shared query, pagination, hook, or transformer behavior for resource endpoints

Do not start here when

• the task is application bootstrap
• the real issue is gateway or reverse-proxy topology
• the work is business repository ownership or domain validation

First files to read in the current repository

1. x/rest/module.yaml
2. x/rest/spec.go
3. x/rest/entrypoints.go
4. reference/standard-service when checking canonical bootstrap shape

Concrete ownership examples

Keep it in x/rest when the work is about	Keep it elsewhere when the work is about
ResourceSpec, route-shape standardization, shared pagination rules, and reusable CRUD transport behavior	route binding and transport composition in app-local wiring
DB-resource controller construction and context-aware resource registration	persistence and query execution in the repository layer
aligning controller output with contract response and error conventions	domain validation and business rules in owning domain packages
reusable resource-interface transport for many services	edge proxy, gateway policy, or reverse-transport concerns in x/gateway

Usage

Import

import "github.com/spcent/plumego/x/rest"

Register a full CRUD resource

import (
    "github.com/spcent/plumego/router"
    "github.com/spcent/plumego/x/rest"
)

r := router.NewRouter()
rest.RegisterResourceRoutes(r, "/api/v1/users", controller, rest.RouteOptions{})

This registers GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD and batch endpoints under /api/v1/users.

Generated DB controller

builder := rest.NewSQLBuilder("users", "id").
    WithColumns("id", "name", "email", "created_at").
    WithScanFunc(scanUser).
    WithInsertFunc(insertArgs).
    WithUpdateFunc(updateArgs)

repo       := rest.NewBaseRepository[User](sqlDB, builder)
controller := rest.NewDBResourceController[User]("users", repo)

Parse query parameters

params := rest.NewQueryBuilder().
    WithPageSize(25, 100).
    WithAllowedSorts("name", "created_at").
    WithAllowedFilters("email").
    Parse(r)
// params.Page, params.PageSize, params.Sort, params.Filters, params.Search

Custom controller

Embed BaseResourceController and override only the methods you need:

type UserController struct {
    rest.BaseResourceController
    svc *UserService
}

func (c *UserController) Create(w http.ResponseWriter, r *http.Request) {
    // your logic
}

For the full walkthrough see the Build a REST Resource guide.

Canonical reading move

If the top-level page told you the problem belongs to an extension family, x/rest is the right next read only when the work is about reusable resource-interface transport. It is not the place to invent a new bootstrap shape.

Read next

• Build a REST Resource guide
• Reference App
• Store Primer
• Repository Boundaries