API Testing with Postman

A food delivery app had a neat little quantity stepper: the – button stopped at 1, so you could never order fewer than one pizza. The UI was tested carefully and worked perfectly.

Then someone sent the request to the server directly, with "quantity": -3. The server accepted it. The order total went negative, and the “refund” landed on a real card.

The bug was never in the screen. It was in the APIAPIThe way different software parts talk to each other, like an app asking a server for data.Open in glossary → behind it, and the UI was simply hiding it. This lesson teaches you to test that layer directly, with Postman, the most popular tool for the job.

Why it matters

Almost every modern app is two parts: a front end (the website or the mobile app you see) and a back end (servers and databases). They talk to each other through APIs. The same API often serves the website, the iOS app, the Android app and partner companies.

That means:

• One API bug breaks every platform at once.
• The UI can hide bugs. A form may block bad input, but the API might still accept it from anyone who sends a request directly.
• API tests are fast. You can check 20 cases in the time it takes to click through one checkout.
• Bugs are easier to pin down. If the API returns the wrong data, it’s a back-end bug. If the API is right but the screen is wrong, it’s a front-end bug. That makes your bug reportsBug reportA clear written description of a bug so developers can reproduce and fix it.Open in glossary → much sharper.

What is an API?

An API (Application Programming Interface) is a set of rules that lets one program ask another program for data or actions.

The classic analogy is a restaurant:

The menu is the API documentation: it lists what you can order and how. As an API tester you skip the dining room (the UI) and talk to the waiter directly: you order normal dishes, strange dishes, dishes that aren’t on the menu, and you check that the waiter always responds correctly.

REST basics

Most web and mobile APIs today are REST APIs. They use plain HTTP, the same protocol your browser uses, and usually send data as JSONJSONA simple text format for data, used by most APIs, like {"name": "Anna", "age": 31}.Open in glossary →. Every call is a request from the client and a response from the server.

Endpoints and URLs

An endpointEndpointA specific API address the app calls, like GET /api/products or POST /api/login.Open in glossary → is one address of the API that does one job. A URL has several parts:

Part	Example	Meaning
Base URL	https://api.shop.test/v1	Where the API lives (often different per environment)
Path	/products	Which resource you want
Path parameter	/products/42	Which one item (here product 42)
Query parametersQuery parameterData in a URL after the ?, like ?q=mug&sort=price, often used to keep search and filter state.Open in glossary →	?category=shoes&limit=10	Filters and options, after a ?, joined with &

Methods

The HTTP methodHTTP methodThe type of request: GET reads data, POST creates, PUT/PATCH updates, DELETE removes.Open in glossary → says what you want to do with the resource:

Method	Does	Example	Has a body?	Idempotent?
GET	Read	GET /products/42	No	Yes
POST	Create / trigger an action	POST /cart/items	Yes	No
PUT	Replace / set completely	PUT /cart/items/42 with {"quantity": 3}	Yes	Yes
PATCH	Change some fields	PATCH /profile with {"name": "Ana"}	Yes	Not necessarily
DELETE	Remove	DELETE /cart/items/42	Usually no	Yes

Status codes

Every response starts with an HTTP status codeHTTP status codeA three-digit number in every server response: 200 means OK, 404 not found, 500 server error.Open in glossary →. The first digit tells you the family:

Code	Name	When you’ll see it
2xx	Success
200	OK	A read or update worked
201	Created	Something new was created (POST)
204	No Content	Worked, nothing to send back (often DELETE)
3xx	Redirection
301 / 302	Moved Permanently / Found	Go to another URL
304	Not Modified	Use your cached copy
4xx	Client error (the request was wrong)
400	Bad Request	Invalid data, missing field, broken JSON
401	Unauthorized	Who are you? No token, or an invalid / expired one
403	Forbidden	I know who you are, but you’re not allowed
404	Not Found	The resource doesn’t exist
405	Method Not Allowed	E.g. DELETE on an endpoint that only supports GET
409	Conflict	Clashes with current state, e.g. creating a duplicate
422	Unprocessable Content	The JSON is valid but the values break a rule (some APIs use 400 for this)
429	Too Many Requests	Rate limit hit
5xx	Server error (the server failed)
500	Internal Server Error	Unhandled crash on the server: almost always a bug
502 / 503 / 504	Bad Gateway / Service Unavailable / Gateway Timeout	Server down, overloaded or too slow

Headers

Headers are key–value pairs with extra information about the request or response:

• Content-Type: application/json — “the body I’m sending is JSON”.
• Authorization: Bearer eyJhbGci... — “here’s my token, this is who I am”.
• Accept: application/json — “please answer in JSON”.
• Response headers like Cache-Control, Location (where a new resource lives) or X-Request-Id (great to paste into bug reports so developers can find the server log).

JSON bodies

POST, PUT and PATCH usually send a body in JSON: keys in double quotes, values as strings, numbers, true/false, null, arrays [ ] or objects { }.

{
  "productId": 1,
  "quantity": 2,
  "giftWrap": false,
  "note": "Leave at the door"
}

Notice that 1 (a number) and "1" (a string) are different types. Many API bugs are type bugs.

Authentication: tokens and API keys

Most APIs need to know who is calling:

• Bearer token. You log in once (e.g. POST /login), the server returns a token, and you send it on every request in the header Authorization: Bearer <token>. Tokens expire. A common format is a JWT (a long string starting with eyJ).
• API key. A fixed secret string for an app or partner, sent in a header like x-api-key: ... or sometimes as a query parameter.

The two error codes to remember: 401 = missing or invalid credentials; 403 = valid credentials, but not allowed (for example a customer trying an admin endpoint).

Why test the API directly?

Reason	Example
Faster feedback	Check 15 invalid inputs in two minutes, no clicking through screens
Finds bugs the UI hides	The UI greys out ”–” at 1, but the API accepts -5
Validation bypass	Front-end checks can be skipped by anyone. The server must validate everything again.
Earlier testing	The API is often ready days before the screens are
Clear blame	Wrong data in the API response → back-end bug. Correct response but wrong screen → front-end bug.
Security checks	Call another user’s resources with your token to test access rules (see Security Basics)

Try it: a mini API client

Here’s a simplified Postman-like client connected to a simulated Shop API that runs in your browser. Nothing is sent over the internet. Try these:

Shop API ›GET · List productsGET · Get productGET · View cartPOST · Add to cartPUT · Update cart itemDELETE · Remove cart itemPOST · Create coupon (admin)DELETE · Delete product (admin)

Shop – TestNo environment

GETPOSTPUTPATCHDELETESend

GET https://api.shop.test/v1/products?category=accessories&limit=10

Params²Headers²BodyTests²

curl

Query parameters are added after a ? in the URL. Edit here or in the URL bar.

Add param

Response

Click Send to get a response.

History

Reset data

Requests you send appear here.

API docs (what the API promises)

Postman essentials

Postman is an app (desktop and web, with a free plan) for building, sending, saving and automating API requests. Here’s what you’ll use every day.

A few tests worth knowing, in Postman’s JavaScript syntax:

// Status code
pm.test("Status code is 200", () => {
  pm.response.to.have.status(200);
});

// Response time
pm.test("Response time is below 500 ms", () => {
  pm.expect(pm.response.responseTime).to.be.below(500);
});

// Body content and types
pm.test("Product has the right shape", () => {
  const json = pm.response.json();
  pm.expect(json.id).to.eql(1);
  pm.expect(json.name).to.be.a("string");
  pm.expect(json.price).to.be.a("number");
});

// Header
pm.test("Content-Type is JSON", () => {
  pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");
});

// Save a value for the next request (e.g. after POST /login)
pm.environment.set("token", pm.response.json().token);

What to test

Positive (happy path): each endpoint with valid data returns the documented status (200, 201, 204) and body · created items can be read back with GET · updates really change the data · lists support their filters, sorting and paginationPaginationSplitting a long list into pages that load one at a time.Open in glossary →.

Negative: input validation. input validationInput validationChecking that what the user typed is acceptable before the app uses it.Open in glossary → on the server is the heart of API testing:

• Missing required fields → 400 with a message naming the field.
• Wrong types: "quantity": "two", "price": "19.99", null, an array instead of an object.
• Boundary values (boundary value analysis): if quantity is 1–10, try 0, 1, 10, 11, and also -1 and 1.5.
• Invalid JSON (a missing bracket) → 400, not 500.
• Extra or unknown fields like "isAdmin": true are ignored or rejected, never applied.

Negative: auth and existence.

• No token or an invalid / expired token → 401.
• Valid token but no permission → 403. Another user’s resource → 403 or 404.
• An ID that doesn’t exist → 404, not 200 with an empty body.
• Creating a duplicate (same email, same coupon code) → 409, not 500.
• Wrong method on an endpoint → 405.

Behavior:

• Idempotency. Send the same PUT or DELETE twice; the result must be the same as sending it once.
• Response schema and data. Field names, types and formats match the docs (dates, currencies, IDs). No missing fields, no extra sensitive fields like passwords or other users’ emails.
• Response time. Agree on a target (e.g. under 500 ms in the test environment) and watch for slow endpoints.
• Error messages are clear, consistent and don’t leak stack traces or SQL (see error messageError messageText that tells the user something went wrong and, ideally, how to fix it.Open in glossary →).

Common API bugs

#	Bug	What you see	Typical severity
1	Missing server validation	quantity: -5 or 0 is accepted, totals go negative	High
2	Wrong status code	200 with null or {} instead of 404; 200 with {"error": ...}	Medium
3	500 instead of 4xx	A duplicate, missing field or bad JSON crashes the server	Medium–High
4	Missing auth check	An endpoint works without a token, or for the wrong user	Critical
5	Type / schema mismatch	"price": "19.99" (string) where the docs say number; renamed fields	Medium
6	Not idempotent	Repeating PUT adds the item again; a retried payment charges twice	High
7	Over-sharing	The response includes password hashes, internal IDs or other users’ data	High–Critical
8	Leaky errors	Stack traces, SQL queries or server paths in error messages	Medium
9	Inconsistent errors	Each endpoint returns errors in a different format	Low
10	Slow endpoints	A list call takes 4 seconds once there are 1,000 items	Medium

Find the bug

Here’s the same client connected to a buggy build of the Shop API. The API docs at the bottom say what the API promises. Compare the real responses with the docs, and use the Tests tab and History to help.

🐞 Bug hunt: Shop API test build

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

Shop API ›GET · List productsGET · Get productGET · View cartPOST · Add to cartPUT · Update cart itemDELETE · Remove cart itemPOST · Create coupon (admin)DELETE · Delete product (admin)

Shop – TestNo environment

GETPOSTPUTPATCHDELETESend

GET https://api.shop.test/v1/products?category=accessories&limit=10

Params²Headers²BodyTests²

curl

Query parameters are added after a ? in the URL. Edit here or in the URL bar.

Add param

Response

Click Send to get a response.

History

Reset data

Requests you send appear here.

API docs (what the API promises)

• GET/productsPublic Try it

  List products. Query: category (string), limit (integer 1–50). Returns { data: Product[], total }. Product = { id: integer, name: string, price: number, category: string, inStock: boolean }.

  200 · 400 bad limit

• GET/products/{id}Public Try it

  One product.

  200 Product · 404 if it does not exist

• DELETE/products/{id}Admin token Try it

  Delete a product.

  204 · 401 no/invalid token · 403 not an admin · 404

• GET/cartToken Try it

  The current user’s cart: { items, total: number }.

  200 · 401

• POST/cart/itemsToken Try it

  Add a product. Body { productId: integer, quantity: integer 1–10 }. Adds to any quantity already in the cart.

  201 · 400 invalid body · 401 · 404 unknown product · 409 out of stock

• PUT/cart/items/{productId}Token Try it

  Set the quantity of a cart item. Body { quantity: integer 1–10 }. Idempotent: sending it twice gives the same result.

  200 · 400 · 401 · 404

• DELETE/cart/items/{productId}Token Try it

  Remove an item from the cart.

  204 · 401 · 404 not in cart

• POST/couponsAdmin token Try it

  Create a coupon. Body { code: string, percent: integer 1–90 }. Codes are unique.

  201 · 400 · 401 · 403 · 409 code already exists

1. 1

   Hint: The docs say quantity must be 1–10. Try values outside that range in Add to cart.

   Adding a negative quantity to the cart is accepted

   POST /cart/items with "quantity": -5 (or 0) returns 201 Created and the cart total becomes negative. Only the upper limit (10) is checked. Expected: 400 "quantity must be between 1 and 10".

   Reveal answer✓ I found this
2. 2

   Hint: Ask for a product ID that is not in the list.

   A product that does not exist returns 200 with null

   GET /products/999 returns 200 OK with the body null. Apps then crash or show an empty page. Expected: 404 Not Found as documented.

   Reveal answer✓ I found this
3. 3

   Hint: Add an item, then untick the Authorization header and remove it.

   Removing a cart item works without a token

   DELETE /cart/items/1 without an Authorization header returns 204 and really deletes the item. Expected: 401 Unauthorized. Missing auth checks are critical security bugs.

   Reveal answer✓ I found this
4. 4

   Hint: Send Create coupon (admin) twice with the same code.

   Creating the same coupon twice crashes the server (500)

   The second call returns 500 Internal Server Error with a raw database message (duplicate key value violates unique constraint). Expected: 409 Conflict with a clear message, and no database details.

   Reveal answer✓ I found this
5. 5

   Hint: Compare the type of price with the docs, or run the price test.

   price is a string, not a number

   Products return "price": "19.99" (a string in quotes) but the docs say number. Apps that add prices may concatenate text ("19.99" + "9.50" = "19.999.50"). The price test fails with expected '19.99' to be a number.

   Reveal answer✓ I found this
6. 6

   Hint: Send Update cart item several times and look at the quantity.

   PUT is not idempotent: each call adds the quantity again

   PUT /cart/items/1 with "quantity": 3 gives 3, then 6, then 9. PUT should set the quantity, so repeating it must always leave 3. Retries on a bad network would silently inflate orders.

   Reveal answer✓ I found this

Reading API docs: Swagger and OpenAPI

Before testing, read the docs. Most teams describe their API in an OpenAPI file (formerly called Swagger), a YAML or JSON file that lists every endpoint, parameter, request body, response and status code. Tools like Swagger UI or Redoc turn it into a readable web page, often at a URL like /docs or /swagger.

As a tester, the docs are your expected results:

• Each documented field, type and status code is something to verify.
• Anything missing from the docs (what happens on a duplicate? what is the max length?) is a question for the team, and often a bug waiting to happen.
• Postman can import an OpenAPI file (Import › file or URL) and generate a whole collection for you.

Alternatives to Postman

Tool	What it is	Good for
Insomnia	Desktop API client, similar to Postman	A cleaner, lighter UI; REST, GraphQL and gRPC
Bruno	Open-source desktop client that stores collections as plain files	Teams that keep API tests in Git next to the code
curl	Command-line tool available on macOS, Linux and Windows	Quick checks, sharing an exact request with a developer
Browser DevTools	Network tab › right-click a request › Copy as cURL / fetch	Grabbing the real request the app sent, then replaying it in Postman (Import › Raw text)

curl -X POST 'https://api.shop.test/v1/cart/items' \
  -H 'Authorization: Bearer <your-test-token>' \
  -H 'Content-Type: application/json' \
  -d '{"productId": 1, "quantity": 2}'

Example test cases

Checklist

API testing checklist

0 of 14 checked

Copy

• I read the API docs (OpenAPI/Swagger) and know the expected status codes
• Requests use environment variables like {{baseUrl}} and {{token}}, no hard-coded values
• Every endpoint returns the documented status and body for valid data
• Created data can be read back, updated data really changed
• Missing fields, wrong types and invalid JSON return 400, never 500
• Boundary values are tested (min-1, min, max, max+1)
• No token / invalid token returns 401, wrong role returns 403
• Unknown IDs return 404, duplicates return 409
• PUT and DELETE give the same result when repeated
• Field names and types match the docs (numbers are numbers)
• Responses contain no sensitive or extra data
• Error messages are helpful and leak no stack traces or SQL
• Response times are within the agreed limit
• Key checks are saved as pm.test scripts in a shared collection

Check your understanding

Quick quiz

0/6 answered · 0 correct

1. 1.You send a request with a valid customer token to an admin-only endpoint. What status code should you get?

   A200 OKB401 UnauthorizedC403 ForbiddenD404 Not Found

2. 2.Which method should be idempotent?

   APOST /cart/itemsBPUT /cart/items/1 with {"quantity": 3}CPOST /ordersDNone of them

3. 3.Creating a user with an email that already exists returns 500. Is that a bug?

   ANo, any error code is fineBYes, it should be a 4xx like 409 ConflictCNo, 500 means the request was wrongDOnly if it happens on production

4. 4.Which Postman script checks that the response status is 200?

   Apm.status(200)Bpm.response.to.have.status(200)Cresponse.code == 200Dpm.expect.status = 200

5. 5.Why use {{baseUrl}} instead of typing https://api.staging.example.com in every request?

   AIt makes requests fasterBYou can switch every request to another environment by changing one variableCPostman requires itDIt hides the URL from the server

6. 6.The UI blocks quantities below 1. Why test quantity -5 on the API anyway?

   AYou should not, the UI already prevents itBAnyone can call the API directly, so the server must validate tooCNegative numbers are not valid JSONDTo test the response time

Key takeaways

• An API is how apps talk to servers. Testing it directly is fast, finds bugs the UI hides, and shows whether a bug is front end or back end.
• Know the basics: methods (GET, POST, PUT, PATCH, DELETE), status codes (2xx success, 4xx client error, 5xx server error), headers, JSON bodies and tokens.
• Remember 401 vs 403, 404 for missing items, 409 for duplicates, and that a 500 caused by user input is a bug.
• In Postman, use environments and variables, organize requests in collections, and automate checks with pm.test and pm.expect.
• Always test validation, auth, idempotency, the response schema against the docs, response time and error messages.

Go deeper: API Testing in Depth covers JWTs and expired tokens, authorization tests, negative requests, response checks beyond the status code, and a FoodDash API sandbox with 8 bugs to find.