API Performance Testing

Why it matters

Every app screen and partner integration is a chain of API calls, so one slow endpoint slows every screen that calls it, and in sequential calls the delays add up. Problems such as an unbounded list or a lock on a popular row stay invisible in functional tests, which send one request at a time with little data.

For the tester, endpoint targets turn "the app feels slow" into a reportable result: which endpoint, which percentile, at what load, against which target. API-level tests can also start as soon as an endpoint exists, long before a full end-to-end load test.

Targets per endpoint, not per API

Endpoints do very different work: a health check returns a constant, a lookup reads one row, a search filters thousands of records, and creating an order writes to several tables and may call a payment provider. One target for "the API", such as "everything under 500 ms", hides regressions in the cheap endpoints and is unreachable for the heavy ones.

A testable target names the endpoint and method, the percentile (p95, often also p99), the threshold, the load at which it must hold, the acceptable error rate and the data condition, such as the page size. Without a load level, "p95 under 200 ms" can neither pass nor fail. Targets come from non-functional requirements or SLOs, from the client's needs (a screen that calls two endpoints in sequence must split its time budget) and from production monitoring. The table is one team's example, not a standard.

Slow work such as a large export should not hold the request open. A common design answers 202 Accepted at once (RFC 9110: accepted for processing, but not completed) and lets the client fetch the result later; you then test two targets, the time to accept and the time until the result is ready.

Shop API: targets at the expected peak (an example agreed by one team)

Endpoint                      Load        p95       p99       Errors
GET  /health                  20 req/s    <= 50 ms  <= 100 ms 0 %
GET  /products/{id}           150 req/s   <= 200 ms <= 400 ms < 0.1 %
GET  /products?q=...&limit=20 60 req/s    <= 500 ms <= 1 s    < 0.1 %
POST /orders                  10 req/s    <= 800 ms <= 1.5 s  < 0.1 %
POST /reports/export          1 req/min   202 Accepted <= 300 ms; file ready <= 60 s

Try it: Response Time Analyzer Try it: API Performance Comparator

Payload size is part of the response time

The response time a client sees includes building, sending and parsing the body. The same endpoint can be fast with 20 items and slow with 2,000, quick on the office network and slow on a mobile connection. Test each endpoint at the sizes it will really send and receive.

• Measure the body raw and as transferred: when the client sends Accept-Encoding: gzip, does the response carry Content-Encoding, and how many bytes does it save?
• Lists must be bounded: test the default page size, the documented maximum and a value above it. limit=100000 should be capped or rejected, not served.
• Grow the data: call the same endpoint for a customer with 5 orders and one with 5,000. Time that grows with the data points to missing pagination or a query per item.
• Apply boundary value analysis to request bodies: time a batch endpoint with 1 item, a typical number and the documented maximum, then send one item above the maximum and expect a fast, documented 4xx, not a slow timeout. For a body over the server's size limit, RFC 9110 defines 413 Content Too Large.

Try it: Response Size Analyzer Try it: Large JSON Dataset Generator

Concurrency: one fast request proves little

A functional API test sends one request at a time, so it shows the best case. Under concurrency, requests compete for worker threads, database connections, locks and downstream calls, and an endpoint that answers in 80 ms alone may queue for seconds. Using the workload models from the earlier lessons, step the load: a single-user baseline, the expected peak (the busiest traffic forecast from analytics or by the business), then above it, which is stress testing. Record p95, p99, throughput and error rate at each step.

Where the requests land matters too. Requests spread over many records test the normal path; many requests on one record, such as a discounted product in a sale, test locking. Design both on purpose: varied test data for the first, one "hot" record for the second.

• Check correctness, not only timing: assert the status and key fields of every response, and afterwards check side effects, such as no oversold stock and no order created twice when a client retried.
• Separate expected refusals from failures: above a documented rate limit expect 429 Too Many Requests (RFC 6585), and count it apart from 5xx errors and timeouts such as 504 Gateway Timeout.

Try it: Concurrent Request Test Generator

Worked example: a shop API before a sale

A shop prepares for a sale weekend. The tester runs the product, search and order endpoints from the table at their peak rates for 15 minutes in a staging environment sized like production, with 20,000 product ids and 2,000 test customers, from load generators on separate machines. The results, as written in the report:

• GET /products/{id}: p95 140 ms, p99 260 ms, no errors. Within target.
• GET /products?q=... with the default limit=20: p95 430 ms, within target. The web app's "show all" button sends limit=200: 1.8 MB uncompressed and p95 1,900 ms. Finding: no maximum page size.
• POST /orders at 10 req/s spread over many products: p95 650 ms, within target. When 50 virtual users order one discounted product at once, p95 rises to 1,400 ms and 2 % of requests end in 504 Gateway Timeout. Finding: requests queue on that product's stock update.
• Afterwards the stock levels match the orders: nothing oversold, nothing duplicated. The concurrency problem is slowness, not data corruption.

Tools: from one request to a scripted load test

Small tools cover the steps around a load test. Mutqan's Response Time Analyzer gives a single-user baseline for one endpoint from up to 20 sequential requests (min, max, average, median and p95); the Response Size Analyzer shows, for a URL or a pasted body, the raw bytes, an estimated compressed size and the largest fields; the API Performance Comparator puts two endpoints side by side; the HTTP Request Benchmark runs a small, bounded benchmark. These tools send their requests from Mutqan's server, so they reach only public URLs and their timings include the network path from that server. None of them generates production-scale load.

For that you need a load generator. k6 runs JavaScript scripts whose thresholds fail the run when a target is missed; Apache JMeter builds test plans in a GUI, reads test data with CSV Data Set Config and should run in non-GUI mode for the real test; Gatling and Locust (Python) are other common choices. The k6 script below encodes the product-lookup target. Load test only systems you own or have written permission to test: to a third-party provider, an unannounced load test looks like a denial-of-service attack.

// Run: k6 run -e BASE_URL=https://staging.example.com product-lookup.js
import http from 'k6/http';
import { check } from 'k6';
import { SharedArray } from 'k6/data';

// 20,000 product ids: varied data, so requests do not all hit one cached record
const ids = new SharedArray('ids', () =>
  open('./product-ids.txt').split(/\r?\n/).filter(Boolean));

export const options = {
  scenarios: {
    product_lookup: {
      executor: 'constant-arrival-rate', // open model: a fixed rate of new requests
      rate: 150,
      timeUnit: '1s',
      duration: '15m',
      preAllocatedVUs: 50,
      maxVUs: 300,
    },
  },
  thresholds: {
    'http_req_duration{endpoint:product}': ['p(95)<=200', 'p(99)<=400'],
    'http_req_failed{endpoint:product}': ['rate<0.001'],
  },
};

export default function () {
  const id = ids[Math.floor(Math.random() * ids.length)];
  const res = http.get(`${__ENV.BASE_URL}/products/${id}`, {
    tags: { endpoint: 'product' },
  });
  check(res, {
    'status is 200': (r) => r.status === 200,
    'body has a price': (r) => r.status === 200 && r.json('price') !== undefined,
  });
}

Try it: HTTP Request Benchmark Try it: Concurrent Request Test Generator Try it: Load Test Data Generator

Frequently asked questions

References

• Certified Tester Performance Testing (CT-PT)ISTQB · 2018ISTQB's specialist syllabus on performance testing: basic concepts, performance measurements, test activities and tasks, and tools.
• RFC 9110: HTTP SemanticsIETF · 2022The meaning of HTTP methods, header fields, status codes and content negotiation, independent of the wire version.
• RFC 6585: Additional HTTP Status CodesIETF · 2012Defines 428, 429 Too Many Requests, 431 and 511, including the Retry-After header for rate limiting.
• Grafana k6 documentationGrafana LabsOfficial documentation for Grafana k6, an open-source and extensible load and performance testing tool.