API smoke checks functional QA should own

A surprising amount of UI testing time goes on discovering that an API is down. The tester opens the app, the list is empty, the spinner never stops, and some time later a developer confirms that the bookings service did not deploy properly. Nothing was learned about the product.

Functional testers often leave API testing to developers and SDETs on the grounds that it is code. I think a small part of it belongs to us. API smoke checks are a handful of requests that show the integrations behind the critical journeys are alive and behaving on this build, and a functional tester is the right owner because we know which journey each one holds up.

What an API smoke test is for

Functional QA owns one question here: if this API misbehaves, which user journey breaks? That mapping turns a technical check into a business-relevant one. “The token endpoint returns 500” is an engineering fact. “Nobody can sign in on this build” is a reason to stop testing and tell people.

A smoke check is shallow on purpose. It asks whether the service is deployed, reachable, configured for this environment and returning something the UI can use. It runs in a minute or two and tells me whether the build deserves an afternoon of journey testing or a message to the developers.

A green collection says the journey is possible on this build. Whether a person can complete it is still a question for a human on the real surface.

Which API checks to include

I keep the collection tiny: authenticate, then create, read and update the entities the UI depends on, plus one unhappy path that should fail gracefully. For a single journey that is usually about half a dozen requests.

I start from the journey, not from the API documentation, which lists everything. I watch what the product actually calls: the network tab in the browser for web, Charles Proxy for a mobile app. Swagger then gives me the shape of each request. The calls the journey cannot finish without are the candidates.

What to assert in each API check

A status code alone is a weak oracle. A 200 with an empty list, or a 201 whose body has no id, passes a status check and breaks the screen. For each request I assert three things at most: the status, the few fields the UI reads, and for anything written, a read-back showing it was stored. The unhappy path gets the same care: the expected 4xx and a message the app can display.

AI helps with the typing. I use Cursor or ChatGPT to draft the Bruno or Postman scaffolding: requests, variables and a first set of assertions. The oracles and the data are mine to confirm, for the reasons in AI in QA without fake confidence.

When and where to run API smoke checks

Run the smokes on the same builds you test in the UI, on the same environment, before the UI session starts and again after each deploy to it. A green mobile app on a broken API is still a broken product, and a green API on a different build says nothing about the one in your hand.

Bruno has its own command-line runner and Postman has Newman, so the same checks can also sit in the pipeline after a deploy.

Three details decide whether the collection survives. It has its own user and data, so it does not depend on what someone else left in a shared environment. It cleans up what it creates. And base URLs and credentials live in environment variables, never in the saved requests, so one collection runs against every environment and no secret ends up in the repository.

How to report a failed API smoke check

When a smoke fails, I write the defect in user language and link the trace. The title names who cannot do what, and on which build. Underneath go the request, the response, the timestamp, the environment and the correlation id if the response carries one. Engineering gets reproducibility and Product gets impact, which is the split I describe in Defects Product thanks you for.

I raise one defect, however many screens fail because of it, and say plainly whether the build is still testable.

The objection: API testing is the developers’ job

Much of it is, and I would not duplicate the unit and integration tests developers own. But those typically run in the pipeline against a freshly built service with its neighbours mocked. The smoke runs against the deployed environment, with its real configuration and whatever the other teams deployed overnight. A wrong base URL, an expired certificate, a missing configuration value, a permission never granted here: a test that runs before deployment cannot see any of them.

What goes wrong on our side is growth. Every incident tempts you to add a request, until the smoke is a suite that takes too long to run before a session and fails for reasons nobody investigates. I prune on one rule: a check stays only if I can name the journey that stops when it fails. Deeper API coverage is a different artefact with a different owner.

None of this needs an SDET. If you can read a request in the network tab and say what the screen needs from the response, you can own seven requests.

The goal is fast signal on the integrations your journeys cannot live without, not a large API suite. With it in place, UI testing starts on builds worth testing, an environment fault is reported as one clear defect in the first few minutes, and the hours that used to go on watching a spinner go on the product.