Project Brief — Comprehensive API Test Suite for a RESTful Booking API

You've spent eight chapters learning what API testing is, why it matters, and how every piece fits together. This capstone gives you something concrete to build with all of it. The scenario is realistic, the deliverables map directly to what a working QA engineer produces in their first month on a job, and the work is tool-agnostic — use whatever you're most comfortable with. Read this brief carefully; the next lesson walks through how to attack it, and the third gives you a checklist to assess your own work.

The scenario

You've just been hired as the lead QA engineer for BookItNow — a small but growing hotel booking platform. The product team has shipped a REST API that the iOS, Android, and web clients all consume. There are no API tests in place. Your manager hands you the API spec on day one and says: "We're growing too fast for hope-driven testing. I need you to build a comprehensive test plan and a test suite. Take two weeks. What would you do?"

Your job over the rest of this capstone is to answer that question — concretely, in writing and code, the way you'd actually do it.

The API surface

BookItNow exposes the following endpoints. Treat this list as the spec; you'll design tests against it.

Authentication

• POST /auth/register — create a new user account (email, password, name).
• POST /auth/login — exchange credentials for a JWT access token and a refresh token.
• POST /auth/refresh — exchange a refresh token for a new access token.

Hotels

• GET /hotels — list hotels with pagination (?page=, ?limit=), filtering (?city=, ?minRating=), and sorting (?sort=price&order=asc). Anonymous-accessible.
• GET /hotels/:id — get one hotel's details. Anonymous-accessible.
• POST /hotels — create a hotel. Admin only.

Rooms

• GET /hotels/:id/rooms — list rooms for a hotel, optionally filtered by date range (?from=&to=).
• GET /rooms/:id — get one room's details.

Bookings

• POST /bookings — create a booking. Body: { roomId, from, to, guests }. Authenticated user only.
• GET /bookings/:id — get a specific booking. Owner or admin only.
• PUT /bookings/:id — modify a booking (dates, guests). Owner only.
• DELETE /bookings/:id — cancel a booking. Owner or admin.

Users

• GET /users/me — get the authenticated user's profile.
• PUT /users/me — update name, email, or password.

Roles

• guest — no auth. Can browse hotels and rooms.
• user — authenticated. Can book, view their own bookings, manage their profile.
• admin — privileged. Can manage hotels, view any booking.

Architecture

Read the diagram with the relationships in mind: a user (created via auth) owns bookings; each booking reserves a room; rooms belong to a hotel. Your test design should reflect those dependencies.

Your deliverables

You'll produce nine artefacts. They build on each other — the strategy guides the test cases, the cases generate the schemas, the smoke tests verify the system is alive. Don't worry about polish on the first pass; aim for completeness, then iterate.

1. API test strategy document

A short (one to two page) write-up answering: scope (which endpoints are in/out), approach (which test types — functional, contract, performance — and in what order), environments (where you'll run tests), tools (your choice — Postman, curl, Python, anything), and risks (what could go wrong, and how you'd mitigate it).

2. Test case inventory

A list of at least 50 test cases, distributed roughly:

• ~20 functional tests (happy paths and key error paths across all major endpoints).
• ~10 authentication and authorisation tests.
• ~10 negative and validation tests.
• ~5 edge case tests (boundary dates, overlapping bookings).
• ~5 pagination, filtering, and sorting tests on GET /hotels.

Each case has: ID, endpoint, request shape, expected status, expected body shape, preconditions.

3. Authentication test suite

A focused mini-suite covering the auth surface: register, login, refresh, expired token, missing token, wrong-role token. Six to ten tests; each is a documented scenario plus an example HTTP request and response.

4. Functional test suite for bookings

The booking flow is the highest-risk area — it touches money, time, and inventory. Cover:

• Happy-path create, read, update, cancel by the booking owner.
• All four operations attempted by a non-owner.
• Validation failures: missing fields, invalid date format, from > to.
• Authorisation: anonymous request, expired token, admin reading another user's booking.

5. Pagination, filtering, and sorting tests

For GET /hotels:

• First page, last page, page beyond total.
• ?city=London returns only London hotels.
• ?minRating=4 returns only hotels rated 4 or higher.
• Combined filter + sort + pagination.
• Invalid parameters: page=0, limit=99999, unknown filter field.

6. Permission matrix

A full grid: roles (guest, user, admin) × every endpoint × expected status codes. Rows are roles; columns are endpoints; cells are the expected outcome (200, 201, 401, 403, etc). This single artefact catches privilege-escalation bugs in one glance.

7. Edge case tests

The tricky ones — domain logic at the boundaries:

• Double booking: same room, same dates, two users. Second one should fail (409).
• Past dates: from = yesterday. Should fail validation (400 or 422).
• Overlapping dates: a booking that overlaps an existing booking on the same room.
• Same-day check-in/out: from = to. Allowed or not? Document and test.
• Overbooking: attempting to book a room that's "fully booked" for the requested dates.

8. Response schema definitions

JSON Schema for the two highest-risk responses:

• POST /bookings (201) — id, roomId, userId, from, to, status, total, createdAt.
• GET /hotels/:id (200) — id, name, city, rating, rooms array, address, etc.

Each schema declares required fields, types, formats (date-time, email), and additionalProperties: false.

9. Smoke test checklist

A list of 10 curl commands that confirm the system is alive after a deploy. Pick the most critical paths: anonymous hotel list, login, get-my-profile, create booking, etc. Each entry has the curl line and the expected status code. The whole list should execute in under 30 seconds.

Constraints and ground rules

• Tool-agnostic. Use Postman, Insomnia, curl scripts, Python with requests, JavaScript with axios, or any combination. The shape of the work matters more than the tool.
• Don't write actual code if you don't want to. Each deliverable can be a markdown document with HTTP examples, JSON schemas, and curl commands. Producing real automated tests is a stretch goal (covered in the review lesson).
• No real BookItNow API. Treat the spec as authoritative. You're designing the test suite from documentation, like you would for a real new project before the build is finished.
• Be opinionated. The point isn't to enumerate every possible test — it's to make defensible choices about depth and coverage. Pick a strategy and write down why.

How to know you're done

You're done with this capstone when:

• The deliverables exist as actual files or documents, not bullet-points-in-your-head.
• A teammate could pick up your test plan and execute it without asking you for clarifications.
• You can answer "what's covered, what's not, and why?" for any endpoint in the API.
• Your permission matrix is complete — every (role, endpoint) cell has an expected status.
• The smoke test list runs end-to-end against the spec without ambiguity.

Why this matters

Most QA engineers spend the first month on a new project doing exactly this work — auditing the API, writing a strategy, building the initial suite, and bringing the team along. Doing it once in a capstone, with feedback to yourself in the review lesson, makes the real version go faster and cleaner when it lands.

The next lesson takes you through the deliverables one by one with concrete worked examples. Read it after you've made a first attempt at this brief — even a rough one — so the walkthrough confirms or corrects your instincts rather than substituting for them.

📝 Capstone task

Block out 4–6 hours over the next few days to attack this brief. Don't try to do it all in one sitting. Recommended order:

1. Re-read the brief and sketch the test strategy in 30 minutes.
2. Walk through each endpoint and rough-out 5–10 test cases per endpoint family. You'll easily clear 50.
3. Build the permission matrix as a spreadsheet. It's the single highest-leverage artefact — do it early.
4. Tackle bookings in depth: it's the highest-risk flow.
5. Sketch the JSON Schemas for the two key responses.
6. Finish with the smoke test list.

Save your work in a folder; you'll evaluate it against the checklist in lesson 3. Onward to the walkthrough.