Go

Keep your Go service and its router. AxiomCore extracts a contract from the Go source and generates a typed web client from it. This guide runs a real Go API on the Chi router and calls it from a browser.

Requirements

You also need two terminals and free ports 8084 and 5176.

1. Get the example

git clone --depth 1 https://github.com/AxiomCore/AxiomCore.git
cd AxiomCore/examples/documentation/go-web

2. Install the Go extractor

Install Go extractor 2026.10.14.2 with the checksummed steps in backend extractors. The CLI runs ~/.acore/bin/axiom-go-extractor, or the binary at the path in AXIOM_GO_EXTRACTOR. In CLI 0.149.1, axiom install <extractor> --module does not find the published build, so install it directly. The binary is named axiom-go-extractor; in Acore source and axiom init, the module alias is axiom-go.

3. Build the contract and start the API

amends "axiom-go:main.go"

project(id: "docs.go.greeting", version: "1.0.0")

cd backend
go mod download
axiom build axiom.acore --out backend.axiom
go run .

Built backend contract: backend.axiom

The extractor loads the package and resolves its types with your Go toolchain, so download modules first (or allow network access during the build). It does not run main or your handlers. The API then listens at http://127.0.0.1:8084.

4. Review the extracted contract

Run axiom inspect backend.axiom for an interactive terminal browser, or axiom explain axiom.acore for JSON. This example extracts one endpoint, greet: GET /greet/{name} with a required string path parameter and a JSON Greeting response with one message string.

The handler rejects names longer than 40 characters with a plain-text 422. That check is Go code, not part of the extracted contract. Review paths, parameters, required fields, response models, authentication and any dynamic route patterns the extractor cannot see before you release.

For your own service without an Acore file, run this from its backend directory:

axiom init main.go --module axiom-go

5. Generate the web client and run it

Open a second terminal in the example root:

cd frontend
npm ci
axiom pull ../backend/backend.axiom --framework atmx-web --name greetings --out generated
npm run dev

npm ci installs the pinned atmx-cli 0.146.7 generator that axiom pull needs; without a local generator, pull fails with npm ETARGET. The FastAPI guide explains what pull writes.

Open http://127.0.0.1:5176 and select Say hello. The page configures the contract for the Go API, awaits runtime startup, subscribes to the query, and disposes the previous subscription when it is replaced.

Verify

curl -fsS http://127.0.0.1:8084/greet/Ada

{"message":"Hello, Ada!"}

Also test an overlong name, CORS from the page, startup failure handling and the generated types.

Security and deployment

• The example API is public and stateless, with no login or database.
• Its CORS middleware allows only http://127.0.0.1:5176 and http://localhost:5176, methods GET and OPTIONS, and the headers content-type, traceparent and x-axiom-cache-mode.
• Extraction describes the supported surface. It does not prove all handler behavior or wrap the service with server-side contract enforcement. Use a server adapter for that separate integration.

Clean up

Stop both servers with Ctrl-C. Delete the example directory to remove its node_modules, generated SDK and build output.

Next steps

• How extraction works
• Use your existing stack
• Add contract checks to CI