How to Test a REST API: Methods, Headers, Status Codes and CORS

What testing a REST API means

Testing a REST API means sending real HTTP requests and checking that the responses are what clients expect: the right status code, the right headers and a body with the right shape. You do this while building an endpoint, when debugging a failing integration, and before relying on a third-party API in production.

A useful mental model is that every request has four parts you control — the method, the URL (including the query string), the headers and the body — and every response has three parts you check: the status code, the headers and the body. Most API bugs come down to one of those seven things being different from what someone assumed.

HTTP methods, safety and idempotency

HTTP semantics (RFC 9110) define two properties that matter for testing. A safe method should not change server state. An idempotent method can be repeated with the same effect as sending it once — which is what makes it safe for clients and proxies to retry after a timeout.

Idempotent describes the effect on the server, not the response: deleting the same resource twice may return 204 and then 404, and that is still idempotent. When testing, send PUT and DELETE requests twice and confirm the second call does not create duplicates or fail in an unexpected way. For POST endpoints that must be retry-safe — payments are the classic example — many APIs accept an idempotency key header so the server can recognise a repeated request.

Reading status codes

The first digit of a status code tells you its class. Check the class first, then the exact code.

• 401 vs 403: 401 Unauthorized means the request has no valid credentials — log in or send a token. 403 Forbidden means the server knows who you are and still refuses.
• 400 vs 422: many APIs use 400 for malformed syntax and 422 for well-formed data that fails validation. Read the body; good APIs explain which field failed.
• 429 and 503: check for a Retry-After header and wait at least that long before retrying.

Testing an endpoint step by step

1. Open the API Tester, choose the method and paste the full URL. If the query string is long, check it in the URL Parser first.
2. Add the headers the API needs. Most JSON APIs need Content-Type: application/json on requests with a body, Accept: application/json, and usually Authorization: Bearer <token>.
3. For POST, PUT and PATCH, add a JSON body. Validate it before sending — a stray trailing comma produces a confusing 400 from the server.
4. Send the request and check the status code first, then the response headers (Content-Type, caching headers, rate-limit headers), then the body.
5. Repeat with bad input on purpose: a missing field, a wrong type, an expired token. Error responses are part of the API contract too.
6. Once it works, export the request as code with cURL to Code so you can repeat the test from a script or CI job.

Understanding CORS and preflight requests

Cross-Origin Resource Sharing (CORS) is a browser security mechanism. When JavaScript on https://app.example.com calls https://api.example.com, the browser only lets the page read the response if the API answers with an Access-Control-Allow-Origin header that permits that origin. The server still receives and processes the request — CORS controls what the calling page may read, not what the server accepts.

For requests that are not "simple", the browser first sends a preflight: an OPTIONS request asking for permission. A preflight is triggered when the method is anything other than GET, HEAD or POST; when the request sets headers outside the CORS-safelisted set (for example Authorization or a custom X- header); or when Content-Type is anything other than application/x-www-form-urlencoded, multipart/form-data or text/plain — which includes application/json.

curl -i -X OPTIONS https://api.example.com/orders \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type, authorization"

A correct response includes headers like these. If any are missing or do not match, the browser blocks the real request:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 600
Vary: Origin

When the request includes credentials (cookies, or fetch with credentials: "include"), Access-Control-Allow-Origin cannot be *; it must echo the specific origin and the response must also send Access-Control-Allow-Credentials: true. Use the HTTP Header Inspector to review response headers side by side.

Making tests repeatable in code

Manual testing finds problems; scripted tests stop them coming back. Keep the checks focused on the contract — status, key headers and the fields clients depend on.

curl -sS -i https://api.example.com/users/42 -H "Accept: application/json"

# Exit with a non-zero code on 4xx/5xx — handy in CI scripts
curl -sS --fail-with-body https://api.example.com/health

const res = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({ name: "Ada", email: "ada@example.com" }),
});

// fetch only rejects on network errors — check the status yourself
if (res.status !== 201) {
  throw new Error(`Expected 201, got ${res.status}: ${await res.text()}`);
}
const user = await res.json();
console.assert(typeof user.id === "string", "id should be a string");

import requests

res = requests.get("https://api.example.com/users/42", timeout=10)
assert res.status_code == 200, res.text
assert res.headers["Content-Type"].startswith("application/json")
assert "email" in res.json()

For more request-building and debugging utilities, browse the API tools category.