Advanced — Add a Go Todo API service

Lesson code: 03 — API. The folder contains the managed App → API → Database inventory, architecture, standalone run instructions and changes from the Database checkpoint. Use the runnable checkpoint below, or continue the Core demo authoring route later in this article.

Continue the managed Todo and PostgreSQL lessons. Add a Go API as the third application service in the same Service Lasso inventory. Keep the Todo UI service, move database access into the API and learn dependency chains and managed API recovery.

Outcome

Stage 3: Add the API. The App calls the API, which reads and writes the Database.

This stage deliberately uses TODO_API_AUTH_MODE=anonymous for the local learning workspace. Other local programs can call its API. The next SSO lesson secures both the App and API with Zitadel; keep this anonymous stage confined to your tutorial environment.

The highlighted service is new in this lesson. Everything inside the boundary is managed by Service Lasso.

Purpose	Service	Responsibility / data path
App	lasso-todo (todo)	Serve the browser UI and proxy /todos to the API's allocated HTTP endpoint.
API	lasso-todo-api (todo-api)	Validate requests and read/write SQL through the Database's allocated endpoint.
Database	lasso-postgres (postgres)	Retain todos in ${SERVICE_ROOT}/runtime/data across service restarts.

Existing platform services

These services also run inside Service Lasso. They support the application path shown above.

Purpose	Service	Responsibility
Management	lasso-serviceadmin (@serviceadmin)	Install, configure, start and stop services; show health and endpoints.
Secrets	lasso-secretsbroker (@secretsbroker)	Provide the platform's managed secret delivery.
Example	echo-service	The starter service already included in the demo.
Runtime	lasso-node (@node)	Run the App's packaged JavaScript.

Run the published lesson checkpoint

In the lesson repository from the previous article, prepare this separate checkpoint:

npm ci
npm run setup -- 03
npm run lesson:03

The host uses published Core and Admin and acquires the pinned service archives; no sibling build is needed. Open the printed loopback Admin URL, complete Initialize Secrets Broker, privately save and acknowledge its recovery material, and continue as local-root. Install/configure/start the application services in Admin, dependencies first, then open Todo's allocated Network URL.

Fresh Intel macOS 11 checkpoints automatically select compatible Broker and managed Node 22 profiles for the machine's OS and CPU. Apple Silicon is a separate compatibility case; consult the lesson platform prerequisites. Setup preserves existing manifests and data: retained Node 24 requires macOS 13.5 or newer, and the older Broker requires macOS 12. Use a separate fresh learning folder for the new pins; do not overwrite a retained workspace.

To carry SQL history forward, stop both checkpoint stacks and use a verified PostgreSQL backup/restore into the new checkpoint before starting the API. Never copy a running database directory. Start PostgreSQL, then the API, then Todo. Confirm your items, add and refresh an item, then stop only the API: Todo must report an unavailable API without saving a new row. Restart the API and confirm recovery.

Type shutdown in the host terminal to stop this owned checkpoint. Restart with npm run lesson:03, then start managed services in Admin again, dependencies first. Host restart preserves data and does not automatically start the application stack. Do not run two hosts against one checkpoint. Checkpoints have separate state and do not copy data automatically.

The first three stages use local learning access. SSO has separate identity and platform prerequisites; this route does not establish Mac SSO support. The desktop stage builds on Windows x64.

Core demo authoring route

The steps below teach source packaging and manual imports in the Core demo. Their existing provider pins are separate from the fresh lesson checkpoint's Mac-compatible selection. On Intel macOS 11, use the checkpoint above.

1. Inspect and package another template-derived service

Use Go1.22+ and Node22+. In your Core checkout terminal:

git clone --branch develop --single-branch https://github.com/service-lasso/lasso-todo-api.git ../lasso-todo-api
gh api repos/service-lasso/lasso-todo-api --jq '.template_repository.full_name'
npm --prefix ../lasso-todo-api ci
npm --prefix ../lasso-todo-api test
npm --prefix ../lasso-todo-api run package
npm --prefix ../lasso-todo-api run verify

The query must print service-lasso/service-template. This separate service repository owns real Go source, manifest, packaging, verification and CI. Its template package/test/verify entrypoints are adapted for Go.

Manifest field	What this service adds
id: todo-api	A separately managed API
artifact.platforms	Native archive and command matching the packaged binary
depend_on: postgres	Start the database before its consumer
endpoints.web	An allocated loopback HTTP API
env	API port and actual PostgreSQL runtime allocation
healthchecks	HTTP readiness includes a real database ping

Go source implements health, create/list and parameterized SQL using the same tutorial_todos table as stage two. The API limits titles to 200 bytes; a long non-ASCII title can therefore receive an API validation error even when the UI's character check accepts it.

Local verification checks native archive structure. Real SQL verification uses TODO_VERIFY_DATABASE_STATE; CI separately executes the held Linux archive against PostgreSQL. Compilation does not qualify runtime behavior on other platforms.

2. Import the API and switch Todo to its proxy

Stop Todo in Admin, preserving data. From Core:

node dist/cli.js services import service-lasso/lasso-todo-api --tag 2026.10.4-02ef566 --services-root workspace/canonical-services-root --workspace-root workspace/demo-instance
node ../lasso-todo/scripts/configure-stage.mjs workspace/canonical-services-root/todo api

Refresh Admin. Install/Configure the API, then start PostgreSQL, API and Todo in dependency order, waiting for healthy. Lasso acquires the pinned checksum-verified native binary and supplies ports, environment, ownership and health. Todo reads the API's runtime allocation when it starts. Do not launch the Go binary manually.

Todo → Go Todo API → PostgreSQL

Inspect dependencies, acquired release/checksum, processes, logs and Network views. The browser receives no database credentials. Open Todo's resolved UI URL.

3. Verify the request path and recovery

1. Confirm todos from stages one and two remain.
2. Add another todo through the browser and refresh.
3. Find Created todo through Go API in API logs to prove the proxy path.
4. Stop only the API through Admin, confirming the action. Create/list must fail; inspect dependency health. A running proxy returns503 while the API is down.
5. Start the API, then Todo if needed, and confirm recovery with all saved IDs.
6. Stop Todo, API and PostgreSQL through Admin; restart in dependency order and confirm the complete set again.

Pass: three managed services recover without losing data and actual requests reach the acquired Go API. A separately launched binary is not a pass.

What the template workflow gave you

Both application services own their GitHub template provenance, source, manifests, platform packages, tests, verification and explicit candidate publication. Consumer manifests pin real development prereleases. Source builds, acquired bytes, runtime evidence, docs publication and GA are separate claims. Follow validate and release when authoring your own service.

Stop services through Admin and keep data. Whole-demo shutdown/recycle remains unqualified #1665. Next: Advanced — Add Zitadel SSO to Todo, wire consumers, or package your app.