Postman and curl: test a customer's API on day one, before writing any code

Picture your first morning at a customer site. Before writing a line of code, you type a curl command, pass along the token the customer has just issued you, and check whether their API really returns what the documentation says it does.

A guide on the Harness blog to building a CRUD API with Node.js and Express recommends Postman for testing endpoints by hand and Jest for automated tests, but says nothing about curl. For a tutorial that makes sense: the API is one you wrote yourself.

At a customer, the situation is reversed. Someone else wrote the API, it may have been running for years, and the documentation may have drifted away from the real code.

So do not treat day-one API testing as a formality. Until you know what the API actually returns, every estimate about the deployment is a guess.

curl answers the question “is it alive?”

The official man page describes curl as a tool for transferring data to or from a server using URLs. That short description also explains why it suits a first morning: a terminal and a URL are all you need to get started.

The first flag worth memorising is -H (or --header). It adds a header to the request, such as an authentication token. Suppose the customer is a logistics company and hands you an order-lookup endpoint:

curl -H "Authorization: Bearer $TOKEN" https://api.khach-hang.vn/orders/123

Note three things straight away: whether the request succeeds, whether the returned fields match the documentation, and how the API reports an error when you drop the header. That last step is often skipped, yet it tells you how the integration you are about to write will have to handle authentication failures.

Postman calls this API unit testing: confirming that an endpoint returns the right response to a specific request. curl does exactly that one job well. But by the fifth request, pasting the token in by hand each time, it starts to get awkward.

Postman saves and chains requests

Once you are sure the API is up, the next question is whether the operations fit together. A post by Solène Lanchec on the Forest Admin blog maps the four CRUD operations to HTTP methods: PUT to replace a whole resource, PATCH to modify only part of it. Customer APIs do not always follow this convention.

You need to find that out before writing code that depends on it.

This is Postman’s job. Build a collection for the orders resource with the four operations: create, read, update, delete. Test each one with three cases: a valid request, a request with no token, and a request with bad data. Four times three makes twelve requests, which is enough to see how the API really responds within the morning.

According to Postman, Collection Runner chains requests into a workflow. You create an order, read it back, PATCH a single field, then read it again. If the other fields have been blanked after the PATCH, the customer’s API is treating PATCH as PUT. Far better to learn this today, while the only thing wiped is test data.

Three common first-day mistakes

The first is relaxing when you see a 200. A success status says nothing about whether the body matches the documentation: a 200 response can still be missing fields, change data types or use different names from the docs. Read the whole body, field by field.

The second is only ever calling the API with a token. You will know what the happy path looks like, but not what an authentication failure returns. When the token expires in production, your code will have to guess.

The third is leaving the collection sitting on your laptop after that first morning. It is only valuable when it is run again, and when others on the team can run it too.

What neither tool does for you

Both tools only send requests. Knowing what to check is still your job. Testsigma’s guide lists contract testing as a distinct type of API test: verifying that the API conforms to its defined spec. If the customer has a spec, compare every response against it systematically.

Testsigma also advises regularly testing for vulnerabilities such as SQL injection, XSS and broken authentication. That requires a deliberate list of test cases; a few extra random requests are not enough. The missing-token request in the collection above is a starting point, not a security test.

To keep the collection from being forgotten, Postman notes that Newman or Postman CLI can run collections and tests in a CI/CD pipeline, while Testsigma recommends automating regression tests along with critical flows. The twelve requests you write today should run automatically every time the customer deploys.

Postman also promotes auto-generated documentation that stays in sync as the collection or spec changes. For an FDE this has practical value: documentation generated from requests you have actually run is something the customer’s team can use after you leave the project.

What to learn first

Learn curl first. It forces you to understand each part of a request: URL, method, headers. Move on to Postman once you know what you want to save and automate. Alongside both tools, get a firm grasp of how CRUD maps to HTTP methods, especially the difference between PUT and PATCH.

When reading job descriptions for FDE or solutions engineer roles, look for phrases such as “integrate with customer APIs” or “debug integrations”. That work happens in the terminal and in Postman. On your CV, rather than writing “proficient in Postman”, describe a specific collection you built: for example, one that caught an API mishandling PATCH, or one that was wired into CI.

At a customer site, the output of day one is not code. It is a collection that records how the API really behaves, so that every line of code that follows rests on verified behaviour.