Topic

REST API + Postman / curl

Definition

Exercising a REST API with a tool such as curl or Postman means issuing HTTP requests with an explicit method, URL, headers, and body, and inspecting the returned status code and JSON — independent of any frontend UI.

In simpler words

Before relying on React, you should be able to call Nest routes yourself with curl or Postman and predict exactly what comes back.

Hands-on API practice for the week: hit /health, walk authenticated CRUD routes, and read ValidationPipe / filter errors.

Open official example (opens in new tab)

After this you can

Call GET /health with curl and read the JSON
Call authenticated list/create routes with the correct headers and body
Carry a login cookie across curl requests (or via Postman’s cookie jar)
Interpret errors returned by ValidationPipe and AllExceptionsFilter
Find and use the Swagger UI at /docs instead of guessing routes

Start with the public route: /health

Definition

A public route is a Nest handler marked to bypass the global authentication guard, making it reachable without any credentials — a natural first target for verifying an API is running.

In simpler words

/health needs no login, so it is the fastest way to confirm the API is up before testing anything that requires a cookie.

HealthController marks its single route @Public(), so JwtAuthGuard (global via APP_GUARD) skips authentication for it entirely.

A quick curl to /health with no headers should return { "status": "ok" } with a 200 — if that fails, nothing else in the API will work either, so always check it first.

Calling health

curl -i http://localhost:3000/health
# HTTP/1.1 200 OK
# { "status": "ok" }

No -H Cookie needed — @Public() skipped the auth guard.

Tickets CRUD with curl — including the cookie

Definition

Because JwtAuthGuard is registered globally, every tickets route requires a valid access_token cookie obtained by first authenticating, which curl must forward explicitly using its cookie-jar flags.

In simpler words

Log in first to get a cookie, save it to a file, then pass that file back on every tickets request — otherwise you will get a 401 before your request even reaches the controller.

curl does not keep cookies between separate invocations by default — use -c cookies.txt to save the Set-Cookie response from login, then -b cookies.txt on every later request to send it back.

The list/get/create/update routes are open to any authenticated user; only DELETE :id requires the admin role via @Roles("admin") — expect a 403 if you try it as a non-admin seed user.

Login, then call tickets (curl)

# 1. Log in and save the cookie
curl -i -c cookies.txt -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@course.local","password":"password123"}'

# 2. List tickets using the saved cookie
curl -b cookies.txt "http://localhost:3000/tickets?page=1&limit=20"

# 3. Create a ticket
curl -b cookies.txt -X POST http://localhost:3000/tickets \
  -H "Content-Type: application/json" \
  -d '{"title":"Wire cookies"}'

# 4. Delete as admin (member gets 403)
curl -b cookies.txt -X DELETE http://localhost:3000/tickets/<id>

The same cookie file authenticates every subsequent request, exactly like a browser would.

Mistake: forgetting the cookie jar

// Wrong — no cookie flags, guard rejects every call
curl -X POST http://localhost:3000/tickets -d '{"title":"x"}'
# 401 Unauthorized

// Right
curl -b cookies.txt -X POST http://localhost:3000/tickets \
  -H "Content-Type: application/json" -d '{"title":"x"}'

Without -b cookies.txt, curl sends no cookie at all — the global JwtAuthGuard rejects the request before TicketsController runs.

Postman, Swagger, and reading errors

Definition

Postman offers a persistent cookie jar and saved collections as an alternative to curl, while Nest’s Swagger UI (served from SwaggerModule.setup) documents and lets you try every route from the running application’s own metadata.

In simpler words

Postman remembers cookies for you across requests in a collection; Swagger at /docs shows every real route with an "Authorize" button so you rarely have to guess a path or body shape.

In Postman, cookies persist automatically for requests inside the same collection/workspace, unlike separate curl invocations that each need explicit -b/-c flags.

A Nest API can serve Swagger at /docs (SwaggerModule.setup("docs", app, ...)) with addCookieAuth("access_token") configured — after logging in via a route, Authorize with the cookie so "Try it out" sends it automatically.

A validation failure returns 400 with a message array (from class-validator) listing each broken field; any other unhandled error returns the same shape from AllExceptionsFilter with a correlationId you can grep in server logs.

A validation error body

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["title must be longer than or equal to 1 characters"],
  "details": [{ "field": "request", "message": "..." }],
  "correlationId": "..."
}

Same shape for every endpoint — that is the point of one global ValidationPipe + one global filter.

Keep in mind

Always test /health first — it rules out "the API isn’t even running".
Save curl cookie jars per role (admin vs member) to quickly demonstrate 403 vs success.
Swagger is generated from real decorators — if a route is missing there, check @ApiTags/@ApiCookieAuth and that its module is imported by AppModule.
Check the message array in error responses before guessing which DTO field is wrong.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. How do you call protected tickets routes with curl?

Concept

Log in, then pass the returned token in an -H "Authorization" headerSend the email and password as -H headers on every protected requestLog in first, save the cookie, then send it with -b on later requestsSave the cookie with -b on login, then replay it with -c afterward

2. Can Postman test cookie auth?

Syntax

Yes — use the cookie jar after a successful login responseYes — but you must copy the cookie into an Authorization header manuallyNo — Postman cannot store Set-Cookie responses between requestsYes — but only after you disable the guards on the login route

3. What does Swagger at /docs list?

Practical

Only the routes explicitly marked with an @ApiPublic decoratorDocumented routes including protected ones (still needing auth to call)Only the routes that succeed without authenticationEvery route plus the SQL each one runs against the database

4. What status do you expect without a cookie on a guarded route?

Logic

403 Forbidden400 Bad Request401 Unauthorized302 Found redirecting to the login route

5. Why prefer curl -c/-b while learning?

Concept

It lets curl decode the JWT payload and print the claimsIt makes the cookie session explicit and reproducible in the terminalIt refreshes the auth cookie automatically before it expiresIt sends the cookie as a bearer token in the Authorization header

6. What should you inspect on a failed request?

Practical

Only the Set-Cookie header, since failures are always auth-relatedThe response time and payload size to diagnose the causeThe TypeORM query log, which is returned in the response bodyStatus code, error JSON body, and correlationId when present

7. How do you send JSON with curl?

Syntax

Use -d with the JSON body; curl sets the JSON Content-Type by defaultUse -H Content-Type: application/json and a -d bodyPass the object with a --json-body curl flagUse -H Accept: application/json so the server parses the body

8. Is logging in once enough for a Postman collection?

Logic

Yes — one login authenticates every request in the collection foreverReuse the stored cookie (or refresh login) for subsequent requests in that sessionNo — each request must include the email and password againYes — but only if every request is in the same collection folder

9. What is a good first smoke test after boot?

Concept

POST a new ticket first to confirm the database accepts writesGET a public health check, then login, then list ticketsLog in first, then delete all tickets to reset the stateCall a migrations endpoint to reset the schema before logging in

10. Why might Swagger Try it out fail on protected routes?

Practical

Swagger sends requests from the server, so cookies never attachThe browser call lacks the auth cookie/bearer Nest expectsTry it out uses GET for every route, so POST bodies are droppedThe guards reject any request whose User-Agent is Swagger UI

11. After this login, the next curl still returns 401. What is missing?

Conceptintermediate

curl -c cookies.txt -X POST localhost:3000/auth/login -H 'Content-Type: application/json' -d '{"email":"a@b.co","password":"pw"}'
curl localhost:3000/tickets   # 401

The second call needs -b cookies.txt to send the saved auth cookieThe second call needs -c cookies.txt to send the cookieLogin must use GET so the cookie is storedAdd -H "Authorization: cookie" to the second call

12. This POST is rejected with an empty or invalid body. Why?

Syntaxintermediate

curl -X POST localhost:3000/tickets -b cookies.txt -d '{"title":"Bug"}'

curl sends -d bodies as multipart, which Nest cannot parseThe -b flag consumes the request body instead of sending cookiesWithout -H "Content-Type: application/json" the body is not parsed as JSONA POST body must be passed with -F rather than -d

13. What status do you expect from this request?

Practicaladvanced

curl localhost:3000/tickets   # no cookie sent

200 with an empty list403 Forbidden404 Not Found401 Unauthorized, because the guarded route has no auth cookie

14. Why does the second request succeed?

Logicintermediate

curl -c jar.txt -X POST .../auth/login -H 'Content-Type: application/json' -d '{"email":"a@b.co","password":"pw"}'
curl -b jar.txt localhost:3000/tickets

It replays the auth cookie saved in the jar from the login responseIt logs in again automaticallyIt sends the password in the URLGET requests never need auth

15. What is a sensible first smoke-test step before login?

Conceptadvanced

# 1) ???  2) login  3) GET /tickets

List all tickets to confirm the guard returns dataHit a public health endpoint to confirm the server is upPOST a login with an empty body to warm up the endpointRun a database migrations endpoint to reset the schema

Checking your session…