HTTP & REST Fundamentals — Methods, Status Codes, Headers & a curl Lab

Hands-on Lab: curl lab on Restful Booker

Target: Restful Booker (public practice API — data resets periodically, other learners use it too, so always create your own data). Docs: restful-booker API docs. Keep a notes table with columns Request, Expected, Actual, Observation.

1. Verify tools. On Windows use Git Bash (CMD/PowerShell quoting differs). Install jq: brew install jq (macOS), sudo apt install jq (Ubuntu) or winget install jqlang.jq (Windows).

   curl --version
   jq --version

2. Health check — look at the status line and headers (-i includes headers). Expected: HTTP/1.1 201 Created. Note it: a health check returning 201 is a quirk, most APIs return 200.

   curl -i https://restful-booker.herokuapp.com/ping

3. List bookings and show only the first three with jq. Then filter with a query parameter.

   curl -s https://restful-booker.herokuapp.com/booking | jq '.[0:3]'
   curl -s "https://restful-booker.herokuapp.com/booking?firstname=Aarav" | jq

4. Create a booking (POST) and capture the id into a shell variable. Expected: JSON with bookingid and the echoed booking. Check the status code: it is 200, while REST convention says 201 — log it as an observation.

   BASE=https://restful-booker.herokuapp.com
   BODY='{"firstname":"Aarav","lastname":"Sharma","totalprice":1500,"depositpaid":true,"bookingdates":{"checkin":"2026-12-01","checkout":"2026-12-05"},"additionalneeds":"Breakfast"}'
   
   curl -s -i -X POST "$BASE/booking" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d "$BODY"
   
   BOOKING_ID=$(curl -s -X POST "$BASE/booking" \
     -H "Content-Type: application/json" -H "Accept: application/json" \
     -d "$BODY" | jq -r '.bookingid')
   echo "Created booking: $BOOKING_ID"

5. Prove POST is not idempotent: run the second command above twice and confirm you get two different ids.
6. Get an auth token (credentials are public on the restful-booker docs page).

   TOKEN=$(curl -s -X POST "$BASE/auth" \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"password123"}' | jq -r '.token')
   echo "$TOKEN"

7. Prove PUT is idempotent: send the same full update twice. Both responses must be identical and a GET afterwards must show the same state.

   UPDATE='{"firstname":"Aarav","lastname":"Sharma","totalprice":2000,"depositpaid":false,"bookingdates":{"checkin":"2026-12-02","checkout":"2026-12-06"},"additionalneeds":"Lunch"}'
   for i in 1 2; do
     curl -s -X PUT "$BASE/booking/$BOOKING_ID" \
       -H "Content-Type: application/json" -H "Accept: application/json" \
       -H "Cookie: token=$TOKEN" -d "$UPDATE"; echo
   done
   curl -s -H "Accept: application/json" "$BASE/booking/$BOOKING_ID" | jq

8. PATCH only one field and confirm the rest is unchanged.

   curl -s -X PATCH "$BASE/booking/$BOOKING_ID" \
     -H "Content-Type: application/json" -H "Accept: application/json" \
     -H "Cookie: token=$TOKEN" -d '{"additionalneeds":"Airport pickup"}' | jq

9. Negative checks. Expected: PUT without token → 403; unknown id → 404. -w prints just the status and time.

   curl -s -o /dev/null -w "no-token PUT => %{http_code}\n" -X PUT "$BASE/booking/$BOOKING_ID" \
     -H "Content-Type: application/json" -d "$UPDATE"
   curl -s -o /dev/null -w "unknown id => %{http_code} in %{time_total}s\n" \
     -H "Accept: application/json" "$BASE/booking/999999999"

10. DELETE and verify. Expected: DELETE returns 201 Created (another quirk — 204/200 is conventional), then GET returns 404.

    curl -s -o /dev/null -w "delete => %{http_code}\n" -X DELETE "$BASE/booking/$BOOKING_ID" -H "Cookie: token=$TOKEN"
    curl -s -o /dev/null -w "get after delete => %{http_code}\n" "$BASE/booking/$BOOKING_ID"

11. Run one call with -v and identify: the TLS handshake, the request headers curl sent (lines starting with >) and the response headers (<). Note the X-Powered-By header — we will revisit it in the security lesson.