Building a Claims Processing Microservice with NATS Micro

The scenario

An insurer's claims-intake service already works as plain request/reply (nats request claims.submit '{...}'), but as more services get built the same way, nobody can answer basic questions without reading source code: what services exist, what subjects do they expose, are they healthy right now? The NATS Micro framework (built into official client libraries and nats-cli) adds structured service discovery and stats on top of ordinary request/reply, at negligible cost.

Step 1 — start NATS

terminal 1

docker run -d --name nats-server -p 4222:4222 -p 8222:8222 nats:latest
nats context add local --server="nats://localhost:4222" --select

Step 2 — a claims service, structured as a NATS Micro service

Client libraries provide a micro.AddService(...)-style API; conceptually, it wraps a normal subscription with a registered name, version, and per-endpoint handlers:

pseudocode — any NATS client library's micro API follows this shape

service = micro.AddService(nc, {
  name: "claims",
  version: "1.2.0",
  description: "Insurance claims intake and status",
})
 
service.AddEndpoint("submit", handler=handleSubmitClaim)   // subject: claims.submit
service.AddEndpoint("status", handler=handleClaimStatus)   // subject: claims.status

For this walkthrough, nats-cli's reply command simulates the endpoint handler so the discovery behavior can be demonstrated without writing a full service:

terminal 2 — simulate the submit endpoint

nats reply "claims.submit" '{"claimId":"CLM-9001","status":"received"}'

Step 3 — callers use plain request/reply, unchanged

terminal 3 — the agent portal, same call shape as any request/reply

nats request "claims.submit" '{"policyId":"POL-55","description":"water damage"}'

Micro doesn't change how callers invoke a service — it changes what you can discover about it without reading its source.

Step 4 — discovery: "what services exist right now, and are they healthy?"

With a real Micro-registered service (not the simulated nats reply above) running, nats-cli's micro commands answer exactly the questions that plain request/reply can't:

terminal 4 — list every registered micro service on the server

nats micro list

terminal 4 — detailed info: endpoints, subjects, version

nats micro info claims

terminal 4 — live stats: request counts, error counts, average latency, per endpoint

nats micro stats claims

Step 5 — versioned rollout: two versions of the same service, side by side

Because the service name/version is part of what's registered (not baked into the subject string itself in most client implementations), operators can run claims v1.2.0 and a canary v1.3.0 simultaneously and compare their stats before fully cutting over — the subject-level routing (e.g. which instance answers which request) still follows the same load-balancing behavior as plain request/reply with multiple responders.

terminal 4 — compare error rates between versions during a canary rollout

nats micro stats claims --json | jq '.endpoints[] | {name, num_requests, num_errors}'

Troubleleshooting

Symptom	Likely cause	Fix
`nats micro list` shows nothing, but requests still work	The service was implemented as plain `nats reply`/manual subscription, not registered via a Micro API	Micro discovery only sees services that actually call the Micro registration API in their client library — plain request/reply still works but won't appear in `micro list`/`micro info`
`nats micro stats` shows a rising error count	Endpoint handler is throwing/returning errors — Micro tracks these automatically per endpoint	Use `nats micro stats <name> --json` to identify which specific endpoint is failing, then check that handler's logs
Two versions of a service seem to answer inconsistently during a canary	Expected if both are plain request-responders on the identical subject — requests load-balance across all responders including the canary	If a canary must only receive a fraction of traffic deliberately (not just whatever this instance happens to pick up), route a percentage of callers to a separate canary subject instead of relying on responder load-balancing alone
`nats micro info claims` errors "service not found"	Typo in the service name, or the service isn't currently running/connected	Confirm the exact registered `name` (`nats micro list`) and that the service process is alive

Recap

Concept	Takeaway
NATS Micro	A thin structure over ordinary request/reply adding name/version/endpoint metadata
`nats micro list` / `info` / `stats`	Answers "what services exist, what do they expose, are they healthy" without reading source
Callers	Unaffected — still plain `nats request`, no protocol change
Versioned services	Multiple versions can run side by side for canarying, observed via per-version stats

The scenario#

Step 1 — start NATS#

Step 2 — a claims service, structured as a NATS Micro service#

Step 3 — callers use plain request/reply, unchanged#

Step 4 — discovery: "what services exist right now, and are they healthy?"#

Step 5 — versioned rollout: two versions of the same service, side by side#

Troubleleshooting#

Recap#