API smoke testing is a shallow, wide check run against a service's critical endpoints right after a build or deploy. It has three properties: health, confirm each service's health endpoint responds; shape, confirm one call per release-blocking route returns the expected status and shape; and reachability, confirm the dependencies that route needs are actually reachable. All three run before anything deeper does. API smoke testing answers one question per service, is this build alive enough to test further, the same question browser-level smoke asks, one layer down.
A checkout page can render pixel-perfect while the orders service behind it is quietly down. Browser smoke catches the first case: does the page show up, does the button respond. It has no way to catch the second, because nothing about a rendered page tells you whether the service three hops downstream ever answered the request.
Three properties answer that question for a service, and none of them is optional. A health endpoint has to respond. One call per release-blocking route has to come back with the status and shape its callers expect. And whatever that route depends on, a database, a cache, another service, has to actually be reachable. Miss any one of the three and the service is not alive in the way that matters, no matter how clean a browser-level check looked.
This is written for the engineer, SDET, or release owner deciding whether a set of services is stable enough to promote today, or handed the job of writing that gate. It is not written for someone designing a request-by-request contract suite, or picking which fields belong in a collection of API tests. That is a real job, just a different one, covered later in this piece.
Extending the Smoke Gate Below the Browser
Smoke testing usually gets explained at the browser: load the login page, add an item to the cart, confirm checkout responds. That is the right first gate for a web app, but a browser only ever exercises the paths a user actually clicks through. Most production systems are made of services a browser never talks to directly: an auth service issuing tokens, an orders service writing to a database, a catalog service serving search results. A browser-level smoke suite can pass clean while any one of those returns a server error under the hood, because the page calling it happens to render a cached result or swallow the failure.
API smoke testing closes that specific gap. Same job as browser smoke, shallow, wide, run first, decision-making rather than diagnostic, just pointed at the API surface instead of the DOM: is each service alive, and does it return roughly what its callers expect, the same question a CI gating job asks before it blocks or promotes a build.
A browser check clears the front door and infers the rest. Service smoke asks each service itself.
An API Smoke Test Example Across Three Microservices
Take a small order-processing system: an auth service issuing session tokens, a catalog service serving product data, an orders service that writes and reads orders. Three services, three owners, one release train. An API smoke testing suite for a microservices system like this needs one health check and one functional check per service, six checks total, not a request-by-request tour of every field in every response.
Here is what that looks like written down, with the call, the expected status and shape, and whether a failure there blocks the release:
| Service | Endpoint | Expected status | Expected shape | Blocking |
|---|---|---|---|---|
| Auth service | GET /health | 200 | {status: "ok"} | Yes |
| Auth service | POST /api/sessions | 200 | {token, expiresAt} | Yes |
| Catalog service | GET /health | 200 | {status: "ok"} | Yes |
| Catalog service | GET /api/products | 200 | {results: [...]} | No |
| Orders service | GET /health | 200 | {status: "ok"} | Yes |
| Orders service | POST /api/orders | 201 | {orderId, status} | Yes |
Five of the six rows are marked blocking, because a failure there means the system cannot do what it exists to do: authenticate a user, or create an order. The catalog row is marked no, because an empty category search degrades the storefront into a bare shelf without breaking checkout on an item already in the cart. That distinction, not the endpoint list, is the actual judgment call in this table, the same one that decides which smoke test cases are worth writing at the browser level.
Are the Dependencies Actually Reachable
A service can pass every check above and still be one broken connection away from failing in production, because a health check and a shape check never ask whether a service can reach the things it depends on: a database, a cache, a downstream service, a payment gateway. That is the third property an API smoke test needs beyond up and shaped-right: reachable.
For the order-processing example, each service depends on something it cannot function without:
| Service | Depends on | Reachability check |
|---|---|---|
| Auth service | Credentials store | Query returns within timeout |
| Catalog service | Search index | Index query returns a result set |
| Orders service | Payments gateway | Gateway health check returns 200 |
None of these three checks calls the dependency's full interface. Each asks one question: can the service reach the thing it needs right now. A dependency check failing here is often the real story behind a failure one layer up: an orders service returning a server error on POST /api/orders because the payments gateway it calls is unreachable, not because the orders service itself is broken.
Each check asks one question, not the dependency's full interface. The broken link is the real story one layer up.
The Human Job Left Is Declaring What's Release-Blocking
Every column in both tables above except one is fully determined by reading the code. The route exists or it does not. The response shape a handler returns is declared in the handler. The dependency a service calls is whatever it connects to at startup. None of that requires a human to notice or remember. It is already written down, just not read consistently by whoever is running the gate by hand.
The one column that is not derivable from code alone is blocking, whether a failure there should stop the release. That is a product call, not a technical one. An empty category search is a bad day for the storefront. An orders service failing to create an order is a broken business. Nothing in the route definition says which is which. Somebody has to make that call once per route and keep it current as routes are added.
That is a sharper version of the same shift smoke testing at the browser goes through: the health, shape and reachability parts of a service smoke suite are more obviously derivable here, because a service's contract, its routes, its status codes, its response shapes, is declared in code in a way a rendered page never fully is. What is left for a human to do collapses to one decision per route: does this block the release, yes or no.
Two different jobs, not two tools competing for one. Smoke clears the build; contract testing holds the agreement.
How Autonoma reaches the service layer
The pain in the section above is not writing six checks for a three-service system. It is keeping that table honest as the system grows past twenty routes, past the point where anyone remembers which ones matter. An API smoke testing suite maintained by hand rots the same way a browser one does: someone adds a route, forgets to add the check, and the gate goes quiet on exactly the thing it existed to catch.
Autonoma reads the routes straight out of the codebase, the same way it derives browser-level smoke checks from a UI's components and flows. For each service it finds a route, a handler, and whatever the handler declares as its response, and turns that into a shallow check: call the route, confirm the status and shape line up. Those checks run against the live, deployed preview rather than a mocked boundary, which is what lets a check catch an orders service that is genuinely unreachable instead of one that merely looks fine on paper. On every pull request, the Diffs Agent re-reads what changed: a new route gets picked up, a removed one gets dropped, and the release-blocking call a human made carries forward instead of resetting to zero.
Mapped onto the tables above: the endpoint and expected-shape columns are what our agents derive directly. The blocking column stays a decision a person makes once, and Autonoma respects it as new routes appear rather than guessing on your behalf. What Autonoma does not do is act as a request-level client you point at a spec and ask to walk every field, every header, and every documented error code. That is a different job, covered below.
The routes regenerate themselves on every pull request. The release-blocking call carries forward.
Where Service Smoke Stops and API Contract Testing Begins
Everything above is deliberately shallow: one call per route, a status code, a rough shape. That is on purpose, and it is a hard boundary worth stating plainly. Autonoma is not an API testing tool. It is behavioural, end-to-end testing: it verifies that a service, exercised through the running application, does roughly what it is supposed to do. It does not validate every field in a response against a schema, walk every documented error code, check backward compatibility between a provider and a consumer, or replace a contract test between two teams that need to agree a payload shape will not change underneath them.
That deeper work belongs to real API frameworks: Postman and Newman for CI-runnable request collections, REST Assured for JVM assertion-heavy suites, Pact for consumer-driven contract testing between services owned by different teams. Our API testing strategy guide covers how to structure that layer, and a rundown of the tools themselves is its own reference. Service smoke and deep API testing are not competing for the same job. Smoke asks whether the build is alive enough to bother testing further. Contract testing asks whether the contract between two services actually holds, one level down from system testing, which checks the fully assembled product as a black box regardless of how any one service was built. Run smoke first, since a service that is down or malformed makes every deeper contract check moot before it starts.
The three-service system here had six blocking decisions and three dependency checks to make once. A real system has dozens of services and hundreds of routes, and by the time anyone writes that table by hand, half of it is already stale. That is the problem worth solving before it is worth automating: get the release-blocking calls made and current, then let the routes underneath them regenerate on their own. Connecting a codebase to Autonoma is how that second part stops being a standing chore, service-layer smoke included.
Frequently Asked Questions
API smoke testing is a shallow, wide check run against a service's critical endpoints right after a build or deploy. It has three properties: a health endpoint has to respond, one call per release-blocking route has to return the expected status and shape, and the dependencies that route needs have to be reachable. Together they answer one question: is this build alive enough to test further.
Browser smoke testing checks the paths a user clicks through: does a page load, does a button respond. API smoke testing checks the services behind those pages directly: does each service's health endpoint respond, does one call per critical route return the expected status and shape, and are the dependencies that route needs reachable. A browser check can pass while a downstream service is failing, because the page calling it may render a cached result or swallow the error. API smoke testing is how that gap gets closed.
Three things per service: a health endpoint to confirm the process is up, one call per release-blocking route to confirm it returns the expected status code and response shape, and a reachability check against the dependencies that route needs, like a database, cache, or downstream service. It should not call every field, every error code, or every edge case; that level of depth belongs to a dedicated API testing framework, not a smoke check.
No. A passing smoke check means the service is up, the route returns roughly the right status and shape, and its dependencies are reachable. It does not mean every field in the response matches a schema, every documented error code behaves correctly, or that two services agree on a contract that will not break later. That deeper verification is the job of contract and API testing tools, not a smoke gate.
Autonoma is behavioural, end-to-end testing that verifies your services through the running application, which is exactly the shape a service-layer smoke gate needs. Its agents read your codebase's routes and derive the checks that matter here, health, expected status and shape, dependency reachability, and the Diffs Agent regenerates them on every pull request, so the gate never drifts from the API it is guarding. That is the part teams usually lose to manual upkeep. Field-by-field schema validation and formal contract guarantees between services are a deeper layer that sits alongside this gate rather than competing with it.
There's no fixed number. The right scope is every service the system cannot function without, judged by what breaks the business if it fails, not by how many services happen to exist. A three-service order-processing system might need six endpoint checks and three dependency checks; a larger system needs more, but the same three properties, health, shape, reachability, still define what belongs in it.
