API Testing
Beginner 12 min read API Testing

API Testing Basics

API testing exercises the HTTP interface between a client and a server: requests, responses, status codes, headers and payloads. Learn to inspect and assert on raw HTTP exchanges so you can verify the contract long before any UI exists.

API testingHTTPRESTendpointsstatus codescurl
Introduction

What is this?

API testing sends real HTTP requests to an endpoint and verifies the response: status code, headers, body and timing. Because the API is the contract every frontend, mobile app and third-party integration relies on, testing it directly catches integration errors that UI tests often miss. It runs fast, needs no browser, and can start as soon as the backend contract exists.

Motivation

Why do you need it?

  • An API bug surfaces the instant a client calls the endpoint, so testing the interface directly finds issues UI tests never reach.
  • Requests execute in milliseconds, letting hundreds of contract checks run in seconds and gate every commit in CI.
  • It exercises the same path mobile apps and partner integrations use, not just the web frontend.
  • Assertions on status, headers, schema and values pin the contract and prevent silent breaking changes.
  • It needs no browser, so the identical suite runs locally, in containers and in CI with the same results.
Think about it

Mental model

Imagine

A waiter taking your order

Think of

An API call

The menu (schema) lists what you can ask for, the ticket (request) spells out exactly what you want, and the plate that arrives (response) must match what you ordered. The API test checks the ticket and the plate match every single time.

Mechanics

How it works

  • Identify the endpoint and method — the URL plus GET, POST, PUT, PATCH or DELETE — that maps to the operation you want to verify.
  • Build the request with the required headers, query parameters, path parameters and body in the documented format.
  • Send it over HTTP and capture the full response: status line, headers, body and timing.
  • Assert on what matters: a 2xx for success, the correct Content-Type, and a body that matches the documented schema.
  • Repeat the same checks across environments and in CI so regressions are caught after every deploy.

One request/response cycle, from the client all the way to the assertion.

Client request
HTTP transport
Server handler
HTTP response
Assertions
Pass or fail
Reference

Key commands

curl -i https://api.example.com/v1/health

Show the response status line and headers along with the body.

HTTP/1.1 200 OK\ncontent-type: application/json\n{"status":"ok"}
curl -X POST -H 'Content-Type: application/json' -d '{"email":"ada@example.com"}' https://api.example.com/v1/users

Send a JSON POST request to create a resource.

curl -s https://api.example.com/v1/users | jq '.'

Pretty-print a JSON response so you can read and copy field paths for assertions.

curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' https://api.example.com/v1/users

Print only the status code and total request time for quick checks.

200 0.042513s
curl --fail --silent --show-error https://api.example.com/v1/users/99999

Fail the command with a non-zero exit code when the API returns a 4xx or 5xx.

Hands-on

Examples

Inspect an endpoint from the terminal

Inspect an endpoint from the terminal
curl -s -i -X GET \
  -H "Accept: application/json" \
  https://api.example.com/v1/users/42
 
# Response (truncated)
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 64
 
{"id":42,"name":"Ada Lovelace","role":"admin"}

-i prints the status line and headers alongside the body so you can assert on the full contract. -s keeps curl quiet, and -X GET makes the method explicit. The 200 status, application/json content type and JSON payload are exactly the three things your tests should verify.

Real world

In production

  • CI pipelines run smoke API checks against staging after every deploy to catch contract breaks minutes after release.
  • Synthetic monitoring calls health and checkout endpoints every minute to alert on downtime before customers notice.
  • A maintained API suite doubles as living documentation that new hires and partner teams read to learn the interface.
  • Pre-deploy compatibility checks verify that existing mobile clients keep working after a backend release.
Guidelines

Best practices

  • Assert on status codes, headers and schema — not merely that the body is non-empty.
  • Keep test data isolated with unique IDs so runs are repeatable and safe to parallelize.
  • Drive the base URL from an environment variable so the same suite runs against dev, staging and prod.
  • Prefer schema validation over exact body matches so harmless field additions do not break tests.
  • Treat 4xx and 5xx responses as testable outcomes too — assert on the error body, not just its absence.
Watch out

Common mistakes

  • Checking only the status code while missing a malformed body or a wrong Content-Type header.
  • Hard-coding tokens, base URLs or IDs inside tests, which makes the suite brittle across environments.
  • Asserting on the entire body verbatim, which fails on any unrelated field change.
  • Testing only happy paths, leaving validation errors, rate limits and timeouts completely uncovered.
Root cause analysis

Common issues

Error
404 Not Found for an endpoint you know exists
Root cause

The URL, base path or version prefix differs from what the server actually routes.

Fix

Compare against server logs and docs; check for a version prefix like /v1/ and for trailing slashes.

Error
415 Unsupported Media Type
Root cause

The Content-Type header does not match the format the server expects.

Fix

Send Content-Type: application/json (or the documented type) and ensure the body is valid for it.

Error
401 Unauthorized instead of the expected 200
Root cause

The request is missing an auth header or is sending an invalid or expired credential.

Fix

Confirm the Authorization header is present and the token or key is correct and not expired.

When things break

Debugging tips

  • Start with curl -i to see the raw status line and headers before writing any test.
  • Capture the exact bytes with a logging proxy to confirm what was really sent versus what you intended.
  • Check the documented schema first — most unexpected failures are payload mismatches, not server bugs.
  • Append the response body to assertion failure messages so CI logs show why a check failed.
Interviews

Interview checkpoint

Practice

Hands-on lab

Your First Endpoint Checks with curl and jq
20 min · beginner
In progress
Objectives
  • Inspect a raw HTTP response including status line and headers
  • Send a POST request with a JSON body
  • Filter and read JSON responses with jq
  • Measure response time and exercise a failure path

Your First Endpoint Checks with curl and jq

20 min · beginner

0/5 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/3
1

Which HTTP status code indicates a resource was successfully created?

2

A 200 OK response guarantees the body matches the documented schema.

3

Your test for GET /v1/users returns 200, but the response body is an HTML login page. What does this suggest?

Quick reference

Cheat sheet

Inspect an API from the terminal
curl -i <url>Show status line and headers
curl -X POST -d '{"k":"v"}' -H 'Content-Type: application/json' <url>Send a JSON POST
curl -s <url> | jq '.'Pretty-print JSON
curl -w '%{http_code} %{time_total}' -o /dev/null <url>Status + timing only
Common status codes
2xxSuccess: 200 OK, 201 Created, 204 No Content
4xxClient error: 400, 401, 403, 404, 422
5xxServer error: 500, 502, 503, 504
Go deeper

Official documentation

MDN — HTTP Overview
docs
MDN — HTTP Request Methods
docs
MDN — HTTP Response Status Codes
docs
RFC 7231 — HTTP/1.1 Semantics and Content
rfc