Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 37 ยท Projects and Practice

Project: Load Testing a REST API from Plan to Report

A complete JMeter project: design the scenarios, build the plan with login, CRUD and assertions, run a staged load, analyse percentiles and write the findings.

In this project you test an imaginary bookstore REST API from start to finish, the way a performance engineer would. You will define goals, design the scenarios, build the test plan, run it in stages and analyse the result. JMeter cannot run on this site, so the plan is described element by element with exact settings, and a Python stand-in simulates the server so you can practice the analysis on realistic-looking numbers. The simulated numbers are invented for the exercise.

The system and the goals

The API has these endpoints:

Method and path Purpose
POST /api/login returns {"token": "..."}
GET /api/books?query=... search books
GET /api/books/{id} book details
POST /api/cart add {"bookId": n, "qty": 1} to the cart
POST /api/orders check out the cart, returns {"orderId": n}
GET /api/orders/{id} order status

Goals (agreed with the product owner):

  • Peak: 150 concurrent users, 60 percent browse, 30 percent search, 10 percent purchase.
  • Search p95 below 600 ms, book details p95 below 400 ms, checkout p95 below 1.5 s.
  • Error rate below 0.5 percent. CPU on the API servers below 70 percent.

Step 1: structure the test plan

TEXT
Test Plan  "Bookstore API"
  User Defined Variables      protocol, host, port via ${__P(...)}
  HTTP Request Defaults       ${protocol}://${host}:${port}
  HTTP Header Manager         Content-Type: application/json, Accept: application/json
  CSV Data Set Config         data/users.csv (email,password), recycle true, sharing All threads
  CSV Data Set Config         data/books.csv (bookId,title), recycle true
  setUp Thread Group          (seed data: 1 thread, 1 loop)
  Thread Group "Browse"       threads = ${__P(browse,90)}
  Thread Group "Search"       threads = ${__P(search,45)}
  Thread Group "Purchase"     threads = ${__P(purchase,15)}
  tearDown Thread Group       (cleanup)

All three Thread Groups use the same ramp-up (${__P(rampup,120)} seconds) and duration (${__P(duration,900)} seconds) with the scheduler enabled and Loop Count set to infinite.

Step 2: build each scenario

Login (inside each scenario, under a Once Only Controller):

  1. POST /api/login with body {"email":"${email}","password":"${password}"}.
  2. JSON Extractor $.token into token, default TOKEN_NOT_FOUND (see extractors).
  3. JSON Assertion that $.token exists.
  4. HTTP Header Manager under the later requests: Authorization: Bearer ${token}.

Browse: GET /api/books/${bookId} inside a Transaction Controller T_BookDetails, followed by a Uniform Random Timer (constant delay 2000 ms, random deviation 3000 ms).

Search: GET /api/books?query=${__RandomString(3,abcdefghijklmnopqrstuvwxyz)} as T_Search, a JSON Extractor $.items[0].id into firstId (default NONE), then GET /api/books/${firstId} guarded by an If Controller with the condition "${firstId}" != "NONE".

Purchase: a Transaction Controller T_Checkout containing POST /api/cart, POST /api/orders, a JSON Extractor for $.orderId, and GET /api/orders/${orderId}. Assertions on 201 for the order and on $.status being PAID or PENDING.

Every request gets a Response Assertion for the status code and, where it matters, a body check. Remember the best practices: meaningful names, think times, no View Results Tree in the real run.

Step 3: run the plan in stages

Terminal
# Smoke: 1 thread each, 2 minutes, with debug listeners enabled in the GUI first
jmeter -n -t plans/bookstore.jmx -Jbrowse=1 -Jsearch=1 -Jpurchase=1 -Jduration=120 -l out/smoke.jtl

# Load: expected peak, 15 minutes
jmeter -n -t plans/bookstore.jmx -Jbrowse=90 -Jsearch=45 -Jpurchase=15 -Jduration=900 \
  -l out/load.jtl -e -o out/load-report

# Stress: 150 percent of peak
jmeter -n -t plans/bookstore.jmx -Jbrowse=135 -Jsearch=68 -Jpurchase=22 -Jduration=900 \
  -l out/stress.jtl -e -o out/stress-report

While the test runs, watch the servers: CPU, memory, garbage collection, database connections and slow-query log. Record the start and end time of each run.

Step 4: analyse (practice with simulated data)

The next block simulates a service whose response times grow as load approaches capacity and then collapse into errors. It is a model (a simple queueing curve) to practise reading results; it is not measured from a real system.

Python Stand-in: simulate three runs and read the numbers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

When you analyse a real run, work through the same questions:

  1. At what load do p95 values cross the goals? That is the knee of the curve.
  2. Does throughput keep rising with threads? If it flattens, a resource is saturated.
  3. When do errors start, and what kind are they (see error analysis)?
  4. What do server metrics show at the same moments: CPU, connection pool, database waits?
  5. Is the generator healthy (sizing)?

Step 5: report

A short, useful report has: the goals, the environment and versions, the three runs with a table of p95, error rate and throughput per transaction, the knee and the first bottleneck found, evidence (charts and server metrics), recommendations (for example "raise the DB pool from 20 to 50, add an index on books.title") and what to retest. Attach the HTML dashboards and the .jtl files.

Extensions

  • Add a soak run: 80 percent of peak for 4 hours; check memory growth.
  • Convert the plan to an open model with a Concurrency Thread Group and Precise Throughput Timer.
  • Wire the smoke stage into a pipeline (JMeter in pipelines).
  • Add a spike: jump from 20 to 300 users in 10 seconds and measure the recovery time.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should the login request live so each user logs in once?

    The Once Only Controller runs its children only on a thread's first iteration.
  2. 2. What does the knee of the response-time curve tell you?

    Near saturation queues build up, so response times rise steeply. The knee marks the practical capacity.
  3. 3. Which problem do the JSON Assertion and the default TOKEN_NOT_FOUND solve?

    Together they make a broken login visible at the step that caused it.
  4. 4. Why watch server metrics during a run?

    CPU, pools, GC and queries show the bottleneck behind slow responses.

Summary

  • Start with goals and a workload mix, then build one Thread Group per scenario.
  • Log in once, correlate the token, assert every response, and use think times.
  • Run smoke, load and stress stages with properties; keep reports per run.
  • Read the knee, throughput flattening, error types and server metrics together.
  • Finish with a short report of results against goals and recommendations.

Next: Project: Capacity Planning and Bottleneck Hunting