Your first API project

Create a Gonex project with the CLI, add an HTTP module, run the server and inspect JSON responses, logs and OpenAPI.

Install the CLI

go install github.com/amkargar/gonex/cmd/gonex@3ca54b46cb42

Use Go 1.27.2 and put Go's binary directory on PATH. See installation for details. This is a pinned development snapshot, not a stable release.

Create your application

gonex new shop --module example.com/acme/shop
cd shop
go mod tidy

You now have your own Go application: main.go, config/, modules/, a pinned framework dependency and a project-local CLI tool. No framework clone or Git commands are part of this setup.

Add an HTTP module

go tool gonex create module users

HTTP is the default transport. This creates a small editable JSON endpoint at /users plus service, handler, schemas and route files. There is no database, gRPC or HTTP API version requirement.

Run and inspect the server

go tool gonex check
go tool gonex run

The terminal displays the actual bound server URL, environment, Gonex version, OpenAPI URL and Ctrl+C instructions after a successful start. Each request emits a completion log with request ID, route, status and elapsed milliseconds. Configure logs for readable development output or production JSON.

From another terminal:

curl http://127.0.0.1:8080/users
curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/openapi.json

The module returns:

json

{"message":"users"}

The response header X-Request-ID matches the request's log correlation ID. Stop with Ctrl+C to drain requests and close resources.

See the development welcome page

Enable debug mode in the process running your application:

DEBUG=true go tool gonex run

On PowerShell:

powershell

$env:DEBUG = "true"
go tool gonex run

Visit http://127.0.0.1:8080/ for Welcome to Gonex, the duck mascot, website and documentation links. A matching application root route takes priority. Browser errors show diagnostics; JSON clients keep their API response format. Use DEBUG=false for public deployments. Debug mode details.

Know where to write code

File	Your responsibility
`modules/users/service.go`	Business behavior, plain Go inputs and results
`modules/users/http/schemas.go`	Request/response DTOs and validation
`modules/users/http/handlers.go`	Request-to-service mapping
`modules/users/http/routes.go`	Endpoint methods, paths and statuses
`modules/users/http/openapi.go`	API descriptions
`modules/users/module.go`	Service construction and adapter wiring

Edit these handwritten files inside your app. Keep .gonex.json and generated registries tool-owned. Generators refuse to overwrite existing module code.

Continue with a real resource API

The starter response demonstrates the structure; it is not generated CRUD. Continue with Build a REST API for create/list/get users, JSON validation, conflict/not-found errors and OpenAPI. That guide starts from a separate generated project so its custom users module does not conflict with this starter.

Project structure explains ownership; CLI reference covers optional database, versioned HTTP and gRPC commands.

Need independent services?

The monolith remains the simplest default. Follow First microservice call when you need independent services; no framework clone is required.

Edit this guide ↗Source snapshot 3ca54b4