API performance test

An API performance test focuses specifically on backend endpoints — REST, gRPC, or GraphQL — to measure latency, throughput, and error rates per endpoint rather than per user journey. It is the tool of choice when you want to benchmark a specific route, compare endpoints across builds, or establish SLOs for individual API operations.

Before you start

• You know which endpoints you want to benchmark (for example, GET /v1/products, POST /v1/cart, GET /v1/runs/$id).
• You have a test environment where these endpoints are reachable and representative of production (similar data set, same service tier).
• You have a smoke test passing against each endpoint.

What is an API performance test?

An API performance test differs from a general load test in scope and intent:

Aspect	Load test	API performance test
Scope	Full user journeys	Individual endpoints
Goal	Validate SLOs under peak traffic	Benchmark and compare endpoints
VU count	Peak concurrency estimate	Enough to see stable p95 (often 10–50 VUs)
Duration	10–30 min	5–15 min per endpoint group
Output	Journey-level metrics	Per-endpoint latency + throughput table

API performance tests are often run:

• During API design to compare different implementation approaches.
• Before and after an optimization to measure improvement.
• In CI to gate per-endpoint SLOs.
• When onboarding MaxoPerf: benchmark your current API before making any changes.

How to run an API performance test in MaxoPerf

Load profile

Parameter	Value
Virtual users (VUs)	50 (adjust based on expected per-endpoint concurrency)
Duration	10 min
Ramp-up	2 min
Stop mode	Duration
Locations	1 (nearest to the API)

Console walk-through

1. Create a test named api-perf-<service>-endpoints.

2. Write a Taurus YAML that covers the endpoint set you want to benchmark. Use meaningful labels so the MaxoPerf results panel shows per-endpoint breakdown:

   execution:
     - executor: jmeter
       concurrency: 50
       ramp-up: 2m
       hold-for: 10m
       scenario: api-bench
   
   scenarios:
     api-bench:
       requests:
         - url: https://api.staging.example.com/v1/products
           label: GET-products
         - url: https://api.staging.example.com/v1/products/prod-42
           label: GET-product-detail
         - url: https://api.staging.example.com/v1/cart
           label: POST-cart
           method: POST
           headers:
             Content-Type: application/json
           body: '{"userId":"bench-user-1","items":[{"productId":"prod-42","qty":1}]}'
         - url: https://api.staging.example.com/v1/checkout
           label: POST-checkout
           method: POST
           headers:
             Authorization: "Bearer ${TOKEN}"
           body: '{"cartId":"cart-99"}'

3. Use the Think time setting to separate requests by a small delay if you want to model realistic inter-request pacing rather than maximum throughput.

4. In Load profile, set Virtual users to 50, Ramp-up to 2m, Duration to 10m.

5. Click Run. While the run is active, the Overview tab will show per-label throughput and latency breakdowns as results stream in.

Tip

For authenticated endpoints, use MaxoPerf secrets to inject tokens without hard-coding credentials in the test file. See Manage test secrets.

How to read the result

Open the Overview tab after the run. Key observations:

• Per-endpoint latency breakdown — the results panel groups metrics by request label. Compare p50/p95/p99 latency for each endpoint. Outlier endpoints (e.g., POST-checkout at 800 ms p95 while all others are under 200 ms) are your optimization targets.
• Throughput per label — compare RPS across endpoints. A low-throughput endpoint with a high VU count may indicate response time inflation from a slow dependency.
• Error rate per label — non-zero error rates on specific endpoints narrow the debugging scope immediately.

Use the run comparison feature to compare this run against a previous benchmark to quantify optimization improvements.

Do / don’t

Do	Don’t
Use meaningful per-endpoint labels so results are readable	Use a single generic label for all requests — you lose per-endpoint visibility
Isolate endpoints you want to benchmark from unrelated traffic	Mix unrelated endpoints in the same test — it obscures which endpoint is slow
Use secrets for authentication tokens	Hard-code credentials in the test YAML
Compare against a prior benchmark run	Claim an endpoint is “fast” based on a single run
Set per-endpoint failure criteria for CI gates	Run without failure criteria and manually review every result

Where to go next

• Baseline regression test — track per-endpoint regressions across builds.
• Frontend / browser performance test — measure browser-rendered performance instead of API throughput.
• Cookbook: REST API CRUD load test — a step-by-step recipe for a full CRUD endpoint benchmark.
• Foundations: Core metrics explained — understand RPS, error rate, and percentiles in the context of API testing.
• By engine: HTTP and REST — protocol-specific MaxoPerf notes for REST API testing.