Handlers & Resources

ShipQ’s API layer is intentionally simple: handlers register themselves with metadata, then the handler compiler generates everything around them — server wiring, OpenAPI specs, test clients, and TypeScript clients.

Generating Resources

The fastest way to get a working API is shipq resource, which generates querydefs, handlers, and tests in one shot.

Generate all CRUD operations

shipq resource pets all

This creates:

File	Method	Route	Description
api/pets/create.go	POST	/pets	Create a pet
api/pets/get_one.go	GET	/pets/:id	Get a single pet by ID
api/pets/list.go	GET	/pets	List pets (with pagination)
api/pets/update.go	PATCH	/pets/:id	Update a pet
api/pets/soft_delete.go	DELETE	/pets/:id	Soft-delete a pet
api/pets/register.go	—	—	Handler registration function

Plus query definitions in querydefs/ and test files in api/pets/spec/.

Generate individual operations

You don’t have to generate all five at once:

shipq resource pets create
shipq resource pets get_one
shipq resource pets list
shipq resource pets update
shipq resource pets delete

Public vs. auth-protected routes

If you’ve run shipq auth, routes are auth-protected by default (controlled by protect_by_default = true in shipq.ini). To make routes public:

shipq resource pets all --public

Handler Registration

Every handler in ShipQ registers itself with metadata that the handler compiler uses for code generation. The register.go file in each API package is responsible for this.

How handler metadata works

When you write (or generate) a handler, it describes itself via a handler.HandlerInfo struct:

• HTTP routing: method (GET, POST, PATCH, DELETE) and path (e.g., /pets/:id)
• Path parameters: automatically extracted from the path pattern (e.g., id from /pets/:id)
• Authentication: whether the handler requires auth, allows optional auth, or is fully public
• Request type: the struct that represents the request body (nil for GETs with no body)
• Response type: the struct that represents the response body

This metadata is what powers OpenAPI generation, TypeScript client codegen, test client generation, and admin UI generation.

Request and response types

Handlers use plain Go structs for request and response types. ShipQ inspects struct tags to determine JSON field names, required fields, and omitempty behavior:

type CreatePetRequest struct {
    Name    string `json:"name"`
    Species string `json:"species"`
    Age     int    `json:"age"`
}

type CreatePetResponse struct {
    ID        string     `json:"id"`
    Name      string     `json:"name"`
    Species   string     `json:"species"`
    Age       int        `json:"age"`
    CreatedAt time.Time  `json:"created_at"`
}

Fields without omitempty and that aren’t pointers are treated as required in the OpenAPI spec.

Handler Compilation

After you’ve added or modified handlers, compile the handler registry:

shipq handler compile

This runs the handler compiler, which:

1. Discovers all handler registration functions across your api/ packages
2. Extracts full metadata: HTTP method, path, path params, request/response struct definitions, auth requirements
3. Generates all the downstream artifacts

What gets generated

Artifact	Location	Description
Server main	cmd/server/main.go	Runnable HTTP server with all handlers wired up
OpenAPI spec	GET /openapi (dev/test)	OpenAPI 3.1 JSON spec
Docs UI	GET /docs (dev/test)	Interactive API documentation
Admin UI	Generated from OpenAPI	Useful for manual testing
HTTP test client	api/*/spec/	Typed test client for each resource
Test harness	api/*/spec/	Test setup/teardown helpers
Integration tests	api/*/spec/	RBAC, tenancy, and 401 tests
TypeScript client	Configurable output dir	Typed HTTP client for your frontend
React/Svelte hooks	Configurable output dir	Optional framework-specific helpers

The handler generate alternative

For more control over what gets generated, you can use handler generate instead of resource:

shipq handler generate posts

This generates the same CRUD handler files but gives you more flexibility to customize before compiling.

Customizing Generated Handlers

Generated handler files are yours to modify — they’re not overwritten on subsequent compiles unless they have the // Code generated by shipq. DO NOT EDIT. header or a zz_generated_ filename prefix.

Files you CAN safely edit

• api/<table>/create.go
• api/<table>/get_one.go
• api/<table>/list.go
• api/<table>/update.go
• api/<table>/soft_delete.go

Files you should NOT hand-edit

These are overwritten on every shipq handler compile:

• Any file starting with zz_generated_
• Any file with the // Code generated by shipq. DO NOT EDIT. header
• cmd/server/main.go

Adding Custom Handlers

You can write handlers from scratch alongside generated ones. The pattern is:

1. Create an API package (e.g., api/reports/)
2. Write your handler function with request/response structs
3. Write a register.go that registers the handler with the registry
4. Add query definitions in querydefs/ if you need custom queries
5. Run shipq handler compile to regenerate server wiring

As long as your handler registers itself correctly, ShipQ’s handler compiler will pick it up and include it in the OpenAPI spec, test client, TypeScript client, and server wiring.

Nested Resources

ShipQ handles foreign key relationships naturally. If you create a books table that references authors:

shipq migrate new authors name:string bio:text
shipq migrate new books title:string author_id:references:authors
shipq resource authors all
shipq resource books all

The generated books handlers will include the author_id field in request/response types, and the OpenAPI spec will reflect the relationship. Foreign key columns are resolved to their correct types (e.g., the author_id field in the request body will reference the appropriate type, not a raw int64).

Iteration Workflow

The typical handler development loop:

# 1. Generate or edit handlers
shipq resource <table> all
# ... or hand-edit api/<table>/*.go

# 2. Add or edit query definitions
# ... edit querydefs/<table>/queries.go

# 3. Recompile queries (if querydefs changed)
shipq db compile

# 4. Recompile handler registry (always needed after handler changes)
shipq handler compile

# 5. Run tests
go test ./... -v

# 6. Start the server
go run ./cmd/server

Tip

shipq resource <table> all runs handler compile for you, so you only need to run it manually when editing handlers by hand or adding new query definitions.