API testing with Postman: a beginner's guide
To test an API with Postman, you send a request (a method, an address, headers and a body), read what comes back (the status code, the body, the headers and the time), and compare it with what the API's documentation promises. Start with GET requests and the documentation, keep the base address in a variable, set the sign-in token once on the collection so every request inherits it, and add a short check under Scripts so Postman confirms the status for you. Then test the refusals: a request without a token, a request for someone else's data, a request with a field missing.
- 8 steps
- from the first request to a collection run
- No code needed
- for manual checks
- 1 practice API
- every example runs against it
How to test an API in Postman, step by step
- Step 1
Get the address and the documentation
Take the API's base address from wherever your team publishes it, and open its documentation. For each request, note the method, the path, the required fields and every status code it lists.
- Step 2
Create a collection and send a GET request
Create a collection for the API. In its View more actions menu, select Add request, keep the method GET, enter the address and select Send.
- Step 3
Read the whole response
Look at the status code, time and size first, then the Body, then Headers. A 200 with the wrong data in the body is still a failed check.
- Step 4
Move the base address into a variable
Select the base part of the address, right-click, choose Set as variable and give it a name such as base_url. Requests then read {{base_url}}/products instead of the full address.
- Step 5
Sign in once for the whole collection
Send the sign-in request, copy the token, and put it on the collection: Authorization, Auth type Bearer Token, Token. New requests in the collection inherit it.
- Step 6
Send a request with a body
Change the method to POST, open Body, choose raw and then JSON, paste the body from the documentation's example and select Send.
- Step 7
Add a check
Open Scripts, then After response, and pick a check from Snippets, such as "Status code: Code is 200". The response's Test Results tab shows how many checks passed.
- Step 8
Run the collection
Select Run on the collection, keep the order of the requests, and select Start run. Every request is sent once and every check is reported in one place.
What API testing with Postman means
An API is the part of an application that other programs talk to. When you add a kettle to the cart in an online shop, the page sends a request to the shop's API, and the API answers with data. Testing the API means sending those requests yourself, without the page, and checking the answers. You reach rules the page hides, and you see the raw reply before any page code tidies it.
Postman is an API client: a program where you build a request by hand, send it and see exactly what came back. It runs as a desktop app for Windows, macOS and Linux, and as a web app. The desktop app can send requests before you sign in; saving work into collections and workspaces needs a free account.
The examples below use the API of Shelf, the practice shop the courses use: kettles, bikes, books, lamps and backpacks, a cart, coupons and orders. Its base address and its OpenAPI description are on the start page of your own sandbox; the guide writes the base address as {{base_url}}.
The parts of a request in Postman
A request in Postman has a method list to the left of the address and a row of tabs under it: Params, Authorization, Headers, Body, Scripts and Settings, with Cookies on the right. The method list holds GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS.
Params holds the query parameters as Key and Value pairs. What you type there also appears in the address, and the other way round. Body is where POST, PUT and PATCH carry their data; for a JSON API choose raw and then JSON, and Postman sets the Content-Type header for you.
GET {{base_url}}/products?category=kettles
Expected: 200, "items" holds kettles only, "total" counts them
GET {{base_url}}/products?category=toys
Expected: 200, "items": [], "total": 0
(an unknown category is an empty list, not an error)How to read the response
The response bar shows the status code, the time in milliseconds and the size, and has the tabs Body, Cookies, Headers with a count, and Test Results with passed and total checks. Read them in that order: the status says whether the request was accepted, the body says what was done, and the headers carry the details a bug report needs.
Here is a request whose status code changes with the state of the cart. The shop's documentation for adding to the cart lists 201 "Added" and 200 "Quantity increased". Product 1 is the Hearthline Classic Kettle 1.7 l at USD 49.00, and the API writes money as a number of dollars.
Every Shelf response carries an x-trace-id header. Copy it into your bug report: it lets a developer find the exact request in the server's logs.
POST {{base_url}}/cart/items
Body (raw, JSON): {"product_id": 1, "quantity": 2}
First time, empty cart:
201 line "quantity": 2, "line_total": 98, "subtotal": 98
Same request again:
200 line "quantity": 4, "line_total": 196Variables and environments
Typing the full address into every request breaks the day the address changes. Put it into a variable instead: select the base part of the address, right-click, choose Set as variable, then in the "Set as new variable" panel fill in Name, check Value, pick a Scope and select Set Variable. Postman writes variables in double braces: {{base_url}}.
A variable can live in one of five scopes, from broadest to narrowest: global, collection, environment, data and local. When two scopes hold the same name, the narrowest one wins. An environment is a named set of values, such as one for a test server and one for a staging server; the selector at the top right switches between them and reads No Environment when none is active.
Authorization, and 401 versus 403
Most of an API needs you to sign in. In Shelf you send your username and password to POST {{base_url}}/auth/login and receive a token that is valid for 8 hours. Put it on the collection: open the collection's Authorization tab, set Auth type to Bearer Token and paste it into Token. A new request in that collection then shows its Auth type as inherited, with an Edit in Parent link, and Postman sends the header Authorization: Bearer <token>.
When you save a collection with a token pasted in, Postman may open "Secrets Detected" and offer to secure the value. Do not share a collection with a live token in it.
The refusals are where APIs most often go wrong, so test them on purpose. 401 means the API does not know who you are: no token, or one that is invalid or expired. 403 means it knows who you are and you are not allowed. Shelf's start page adds a third rule: a 404 can also mean "not yours", so other students' data does not exist for you.
GET {{base_url}}/me with Auth type No Auth
401 "unauthorized": "Sign in first: send Authorization: Bearer <token>."
DELETE {{base_url}}/products/3 with your token (a shared catalog product)
403 "read_only_product": "Products of the shared catalog cannot be
changed. Create your own with POST /api/products."
GET {{base_url}}/orders/1 with your token (an order of another customer)
404 "order_not_found": "There is no order 1 in your account."Checks that run themselves
Reading every response by eye works for ten requests, not for a hundred. Postman can check a response for you after it arrives. Open Scripts, then After response (the documentation calls it Post-response), and either pick a check from Snippets or type one. Snippets include "Status code: Code is 200", "Response time is less than 200ms" and "Response headers: Content-Type header check".
A check is a few lines of JavaScript, but you do not need to program to read one: it has a name and one expectation. After Send, the Test Results tab lists each check by its name as passed or failed. A green check proves only what it checks; read the body as well.
pm.test("Adding to the cart returns 201", function () {
pm.response.to.have.status(201);
});Running a whole collection
Once the requests of a flow sit in one collection, you can send them all in order. Select Run on the collection: the runner shows the Run order of the requests, the Run type (Functional), the Run method (Local) and Iterations. Select Start run, and the results page lists every request with its checks and counts the passed and failed ones.
Order matters. A run that signs in, adds a product, applies a coupon and reads the cart only works if each request leaves the state the next one needs. Start the flow from a known state, such as an empty cart, so the run gives the same result every time.
Mistakes beginners make in Postman
These are the habits that make API checks pass when the API is broken, or fail for reasons that have nothing to do with the API.
Testing only the request that works
Every status code in the documentation is a test. The refusals carry as many defects as the success.
Reading only the status
A 200 with the wrong total is a defect. Compare the body's values with the rule, field by field.
Full addresses in every request
Use {{base_url}}. When the server changes, you edit one value, not forty requests.
A token pasted into each request
Set it once on the collection and let requests inherit it. One expired token then means one place to update.
Checks that depend on the last run
A cart that was not emptied changes 201 into 200. Start from a known state.
No trace id in the report
Copy x-trace-id from Headers. Without it a developer has to guess which request you mean.
Where to learn this
12 lessons
Questions and answers
Do I need to know programming to test APIs with Postman?
No. Sending requests and reading responses needs no code. Automatic checks are a few lines of JavaScript, and Postman's Snippets write the common ones for you.
What is the difference between 401 and 403?
401 means the API does not know who you are: the token is missing, invalid or expired. 403 means it knows who you are and you are not allowed to do this. Sign-in fixes a 401; it does not fix a 403.
Should I use the Postman desktop app or the web app?
Either works. The desktop app sends requests from your computer and can do so before you sign in. The web app sends them through an agent; for addresses on your own computer it needs the Postman Desktop Agent.
Can I test an API without Postman?
Yes. OpenAPI documentation shown in Swagger UI has "Try it out" and "Execute" for one request at a time, and curl sends requests from the command line. Postman adds saved collections, variables, checks and runs.
What should I test first in an API?
One request that should work, then the refusals around it: no token, a missing required field, an id that does not exist, and data that belongs to someone else. Check the status, the body and the headers of each.
More guides
- Start hereHow to become a software testerWhat a software tester does, what to learn and in what order, and how to practice without a job: six steps from zero to a small portfolio.
- Bug reportsHow to write a bug reportThe fields of a bug report, a template to copy, a complete example from a practice shop, severity and priority with examples, and the mistakes that send a report back to you.
- Test casesHow to write test casesThe parts of a test case, a template, a complete example and its negative cases, the difference between a test case, a test scenario and a checklist, and how to fix a weak case.
- Test designBoundary value analysis and equivalence partitioning, with examplesHow to split inputs into equivalence partitions, pick boundary values with the 2-value and 3-value methods, and choose the step, worked through four fields of a practice shop.
- Bug reportsSeverity vs priority, with examplesWhat severity and priority mean, who sets each, the scales teams use, and all four combinations worked through on one practice shop, with a short answer for interviews.
- Test documentationTest case vs test scenario vs checklistWhat a test scenario, a checklist and a test case are, one shop feature written all three ways, when to use which, and how a scenario turns into checklists and test cases.
- Test designHow to test a login pageTest cases for a login page derived from partitions, a decision table, boundaries and states, plus the security checks every login page needs, worked through on a practice shop.
- API testingHow to test a REST API manually: a checklistA manual REST API testing checklist without code: reading the OpenAPI documentation, status codes, body, headers, 401 versus 403, negative cases and state, with example requests to a practice shop.
- DatabasesSQL for testers: check what the app savedHow testers use SQL: the queries that check what an online shop saved after an order (order row, items, payments), SELECT, WHERE, GROUP BY and JOIN on a real schema, and the mistakes to avoid.
- Web testingChrome DevTools for testers: how to collect evidence for a bug reportWhich Chrome DevTools panels a tester needs and how to use them to collect the Console error, the request, the server's response and the storage values that make a web bug report reproducible.
- Test processSmoke vs sanity vs regression testingWhat smoke, sanity, regression testing and retesting usually mean, why teams use the names differently, how to ask on a new team, and how to choose the checks for a new build.
- Mobile testingHow to test a mobile appWhat breaks only on a phone, how to choose between an emulator, a simulator and a real device, how to read the app's log and its traffic through a proxy, and a checklist to start from.
See the first course
The full outline of every course is available: you can see each lesson before you start.