API performance test

An API performance test targets backend endpoints (REST, gRPC or GraphQL). It measures latency, throughput and error rate per endpoint instead of per user journey. Use it to benchmark a specific route, compare endpoints across builds, or set 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 look like 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 purpose:

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

Teams often run API performance tests:

• 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 endpoints you want to benchmark. Give each request a meaningful label so the MaxoPerf results panel breaks results down by endpoint:

   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. To model realistic pacing between requests instead of maximum throughput, use the Think time setting to add a small delay between requests.

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 shows per-label throughput and latency 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 and check:

• Per-endpoint latency. The results panel groups metrics by request label. Compare p50/p95/p99 latency for each endpoint. Outliers (for example, POST-checkout at 800 ms p95 while all others are under 200 ms) are what you optimize first.
• Throughput per label. Compare RPS across endpoints. A low-throughput endpoint with a high VU count may point to a slow dependency inflating response time.
• Error rate per label. A non-zero error rate on a specific endpoint tells you straight away where to debug.

Use run comparison to compare this run against a previous benchmark and measure how much an optimization helped.

Do / don’t

Do	Don’t
Use meaningful per-endpoint labels so results are readable	Use a single generic label for all requests and lose per-endpoint visibility
Isolate endpoints you want to benchmark from unrelated traffic	Mix unrelated endpoints in the same test, which hides 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: RPS, error rate and percentiles in the context of API testing.
• By engine: HTTP and REST: protocol-specific MaxoPerf notes for REST API testing.