rest

README

REST

rest is a Golang application generator inspired by sqlc. SQLC turns SQL into type-safe Go code; rest takes the next step and turns SQLC output or MongoDB contracts into a runnable REST application.

Some parts of this project were developed with assistance from AI coding tools.

Here's how it works:

1. You describe data access with SQLC/PostgreSQL files or MongoDB YAML contracts.
2. You run rest gen.
3. You get a layered Go REST application with repositories, services, HTTP handlers, OpenAPI, auth/RBAC, Docker, tests, and production-oriented middleware.

For SQL projects, rest reads SQL schemas, SQLC queries, and generated Go code, then creates domain models, repositories, services, HTTP transport, OpenAPI, Docker, logging, metrics, security middleware, tests, and curl examples. For MongoDB projects, it reads rest_config/rest_mongo/*.yaml contracts and generates a layered MongoDB HTTP API with custom methods, OpenAPI documentation, auth/security middleware, and Docker output.

Requirements

Required:

• Go 1.25.12 or newer.

Required for SQL projects:

• sqlc: compatible v1.30.0, installed and verified automatically by rest.

Required for running generated applications:

• PostgreSQL for SQL projects.
• MongoDB server for Mongo projects.

Optional but recommended:

• Docker, when docker.enabled or docker.compose.enabled is used.
• govulncheck, used by repository CI through make vuln.

Installation

go install github.com/repomz/rest/cmd/rest@latest

The binary is installed into $(go env GOPATH)/bin. Make sure this directory is included in your PATH.

Verify the installation:

rest version

On the first rest init, the CLI automatically installs the compatible SQLC version into your Go binary directory. rest gen verifies the version again before SQL generation, and rest update keeps the dependency bootstrap in the update workflow.

Install a specific release:

go install github.com/repomz/rest/cmd/rest@v0.1.0

Update an existing installation:

rest update

After installing the release, the command prints its GitHub Release notes, including breaking changes, features, fixes, and documentation updates. Release entries in CHANGELOG.md are generated automatically from Conventional Commits.

Quick Start

Generate a standalone SQL example project:

rest init --example sql
rest gen
go test ./...

Generate a standalone MongoDB example project:

rest init --example mongo
rest gen
go test ./...

Use an existing SQLC project:

rest init
# Set enable: enable and a valid sqlc_path in rest_config/rest_sqlc.yaml.
rest gen

rest doctor
#  At any stage, you're able to run this to see what is missing 
#  and what the project needs before generation or runtime startup.

When rest init runs in an interactive terminal, it briefly checks whether a newer CLI release is available. If an update exists, it asks whether to install it first. Declining the update, running non-interactively, or having no network access does not block initialization.

Commands

Command	Description
rest init	Create rest_config/*.yaml and a customizable rest_sqlc/ project skeleton
rest init --example sql	Create a standalone rest_sqlc_example/ project
rest init --example mongo	Create a standalone MongoDB example contract
rest gen	Generate the REST application
rest doctor	Validate configs, generated files, tooling, Docker/OpenAPI/auth readiness
rest list endpoints	Print the currently discovered endpoints with source and access policy
rest update	Update the CLI from GitHub Releases
rest update --check	Check whether a newer CLI release is available without installing it
rest changelog	Print the latest GitHub Release notes
rest changelog --version vX.Y.Z	Print notes for a specific release
rest version	Print the installed version

For SQL projects, rest gen runs:

sqlc generate -f <sqlc_path>
go mod tidy

Normally no separate SQLC installation is required. To repair it manually:

go install github.com/sqlc-dev/sqlc/cmd/sqlc@v1.30.0

To run SQLC manually, set auto_sqlc: disable in rest_config/rest.yaml, execute sqlc generate -f <sqlc_path>, and then run rest gen.

For MongoDB projects, rest gen reads active rest_config/rest_mongo/*.yaml contracts, ignoring system files that start with rest_, and generates a layered MongoDB API: domain documents, Mongo repositories, services, HTTP handlers, custom method routes, OpenAPI, and optional Docker/Docker Compose output.

Use rest doctor before or after rest gen to catch common setup issues: invalid YAML, unknown fields, missing enabled configs, broken SQLC/Mongo contract paths, missing DB_DSN or MONGO_URI, auth policy conflicts, Docker daemon availability, OpenAPI output gaps, and generated-project readiness.

Use rest list endpoints to inspect the API surface that rest currently discovers from SQLC, Mongo contracts, system routes, and auth configuration.

Contributing

Contributions are welcome. See CONTRIBUTING.md for the local setup, checks, commit format, and pull request guidelines.

License

Licensed under the Apache License 2.0.