REST, JSON, GraphQL & SOAP APIs

The HTTP Request sampler has three tabs below the path. For APIs the choice between them decides how the request body is built:

The component reference lists JSON REST, XML REST and SOAP requests among the uses of the Body Data tab. Once a sampler has Body Data, the GUI does not let you go back to the Parameters tab until the Body Data is cleared. Under the hood Body Data is a single parameter with no name, and the JMX records it with HTTPSampler.postBodyRaw set to true.

Two body-related fields of the sampler matter for APIs:

Source: HTTP Request (Component Reference) and JMeter changes history (5.6.1)

A JSON body is typed into Body Data with variable references where the values change per user or per iteration. JMeter substitutes ${...} references and functions before sending; it does not parse or validate the JSON. The loan request of the Bookshelf journey, for a book id picked from the search results and a due date three weeks ahead:

Steps in the GUI:

The resulting .jmx fragment:

Source: HTTP Request (Component Reference) and __timeShift (Functions)

Three rules keep JSON bodies correct under load:

Large bodies can live in a file and be read once with ${__FileToString(loan-template.json,,)}; the template is re-read on every call, so for hot requests keep it in Body Data. A body that must vary in structure rather than in values belongs in a JSR223 PreProcessor that builds it in Groovy, covered on Scripting with JSR223 & Groovy.

Source: Functions Reference

The HTTP Request sampler does not add Content-Type: application/json on its own. The component reference is explicit for the methods that carry an entity: GET, DELETE, PUT and PATCH require a Content-Type, and if no file is used, a Header Manager attached to the sampler must define it. POST behaves the same way since JMeter 5.0: the property http.post_add_content_type_if_missing (default false, it was effectively true before 5.0) is what used to add application/x-www-form-urlencoded to POSTs without a content type. In the 5.6.3 source, a Body Data body with no Content-Type header is sent by the HttpClient4 implementation as a plain-text entity, so a strict API framework sees text/plain and answers 415 Unsupported Media Type.

The usual arrangement is one HTTP Header Manager at Thread Group level:

Source: HTTP Header Manager (Component Reference) and Properties Reference

The component reference says several Header Managers in scope are merged into one list for the sampler, an entry with the same name replacing the earlier one, and an empty value replacing (not removing) a header. In the 5.6.3 source the manager closest to the sampler is merged first and keeps its value for a name both define, which is what makes "defaults at Thread Group level, adjustments on the sampler" work: a SOAP request below can override Content-Type with its own Header Manager. The user manual’s test-plan chapter states the opposite rule for Header Managers, as discussed under Defaults are merged, three managers are not, so check the headers actually sent (View Results Tree, Request tab, Request Headers) whenever a plan relies on the override.

Two smaller points:

The methods work the same way in the sampler; what changes is where the data goes and what the API is expected to answer. Since 3.1 only POST supports multipart requests and file uploads; PUT and PATCH take their body from Body Data or from a single file with no parameter name.

The 5.6.3 HttpClient4 implementation can also send a body with GET or DELETE when Body Data is set (it switches to an entity-enclosing request); use it only if the API really expects one, because proxies and servers often ignore or reject such bodies.

For PATCH the media type is whatever the API defines. A JSON merge patch is usually sent as application/merge-patch+json and a JSON Patch document as application/json-patch+json; put that header in a Header Manager under the PATCH sampler, which overrides the Thread-Group-level application/json as explained above.

Source: HTTP Request (Component Reference): Method Handling

Search requests carry their data in the query string. There are two ways to build it, and they encode differently:

How the term war & peace ends up on the wire:

__urlencode uses Java’s URLEncoder, which produces application/x-www-form-urlencoded text: spaces become +. Servers decode + as a space in query strings; in a path segment + is literal, so encode path ids (rare in practice, ids are usually safe) with care. The Include Equals? column controls whether name= is sent for an empty value; some APIs treat ?q= and ?q differently.

The query-string parameters in the .jmx:

Source: HTTP Request (Component Reference) and __urlencode (Functions)

JMeter 6.0 plans (per changes.xml on master) to let each HTTP argument row be enabled or disabled individually in the sampler UI, which helps when experimenting with optional query parameters.

By default the HTTP sampler marks responses with a status in the 4xx and 5xx ranges as unsuccessful and everything else as successful. That catches server errors but not contract violations: a 200 where the API should answer 201, or a 302 to a login page, passes. A Response Assertion on the response code makes the expectation explicit.

201 Created on the loan request:

An expected error, such as 404 after the loan was deleted, needs Ignore Status so the 4xx does not fail the sample before the assertion runs:

To accept a family of codes (200 or 204 after a PUT), use Matches with the pattern 20[04] (Assertion.test_type 1), or Equals with Or and two patterns (Assertion.test_type 40).

Source: Response Assertion (Component Reference)

The JSON Assertion first parses the response and fails if it is not JSON, then evaluates a JSONPath expression and fails if the path is not found, and finally, if asked, compares the value found with an expected value. If the path returns an array, the assertion passes when any element matches; [] asserts an empty array; an object is converted to a string before comparison.

Two documented behaviours catch people out. With an indefinite path (one with a wildcard, filter or deep scan, such as $.items[*].id), an assertion without a value used to pass even when nothing matched; since JMeter 5.5 it fails if the path is indefinite, the result is an empty list and no value is asserted. And with Match as regular expression on, an expected value like 1.5 matches 105, because . is a regex metacharacter.

The loan must come back active:

Source: JSON Assertion (Component Reference) and JMeter changes history (5.5)

The JSON JMESPath Assertion (since 5.2) does the same with a JMESPath expression instead of JSONPath; its fields are the same apart from the expression language. The full catalogue of assertions, and how to keep their cost down, is on Assertions.

The JSON Extractor (renamed from JSON Path PostProcessor in 3.1) reads values from a JSON response into variables. It is the standard way to carry ids and tokens from one API call to the next. Its fields, in brief (the detailed treatment with multiple expressions and ForEach loops is on Correlation & Extractors):

The new loan id, read from the 201 response of POST /api/loans:

Source: JSON Extractor (Component Reference)

The Location header of a 201 holds the same id as a URL. A Boundary or Regular Expression Extractor on the Response Headers field can read it when the body is empty; for Bookshelf the body carries the id, so the JSON Extractor is simpler.

The CRUD flow above is a functional check. In the load plan, the borrow journey of the Bookshelf mix (60 % search only, 30 % browse and borrow, 10 % login-heavy) creates a loan on every pass, and the DELETE that returns the book is what keeps the data stable. With the standard load profile (50 threads, 60 s ramp-up, 660 s duration, so a 10-minute hold), assume an average response time of 0.15 s, the section’s average think time of 3 s per request (Z = 3 s), and these requests per iteration: search only 2, borrow 6 (search, view, create, view loan, extend, return), login-heavy 3.

Without the DELETE, about 870 active loans pile up in a single run and the books' available copies run out: later iterations get 409 Conflict instead of 201, the error rate climbs for reasons that have nothing to do with performance, and the next run starts from a different database. With it, a loan lives only from its POST to its DELETE, four requests or about 4 x 3.15 ≈ 12.6 s, so by Little’s Law about 1.44 x 12.6 ≈ 18 loans are open at any moment. A soak test makes the difference larger still. Test-data hygiene is discussed in full on Parameterization & Test Data.

The GraphQL HTTP Request, added in JMeter 5.4, is not a new protocol implementation. The component reference calls it a GUI variation of the HTTP Request: it shows three editors (Query, Variables and Operation Name) and converts them into ordinary HTTP arguments of the same sampler. In the .jmx it is an HTTPSamplerProxy with guiclass="GraphQLHTTPSamplerGui"; at run time it is executed exactly like an HTTP Request.

Compared with the HTTP Request it hides or changes these parts of the GUI:

Everything else (server, port, protocol, path, implementation, timeouts, redirects, keep-alive, proxy, source address) is the HTTP Request’s and behaves the same.

Add it with Add → Sampler → GraphQL HTTP Request.

The GraphQL-specific fields:

The inherited fields used most with GraphQL:

Source: GraphQL HTTP Request (Component Reference)

With POST, the GUI serialises the three fields into one JSON body and stores it as Body Data. In the 5.6.3 source the body is written as an object with the keys operationName (null when the field is empty), variables (left out when the field is empty, copied verbatim otherwise) and query (the trimmed document). The Bookshelf search as a GraphQL operation:

Query:

Variables:

Operation Name: SearchBooks.

JMeter variables and functions are allowed in the three fields (fixed in 5.5 by bug 65108); the body is generated in the GUI and substitution happens at run time, as for any Body Data. Keep ${...} references inside JSON strings in the Variables field ("query": "${term}"), so that the field is valid JSON in the GUI; a bare "first": ${pageSize} is not valid JSON until run time. For a number that must vary, send it as a string only if the schema accepts it, or build the body with Body Data in a plain HTTP Request.

The request still needs Content-Type: application/json, the media type of a GraphQL POST body in the GraphQL-over-HTTP specification. The GraphQL sampler does not add it (the same HttpClient4 rule as for any Body Data applies, so the body would otherwise go out as text/plain). The Thread-Group-level Header Manager of the REST plan covers it.

The resulting .jmx fragment. The GraphQLHTTPSampler.* properties are what the GUI displays; the HTTPsampler.Arguments element is what is actually sent.

Source: GraphQL HTTP Request (Component Reference) and JMeter changes history (5.4 and 5.5)

Because the body is generated by the GUI, editing only GraphQLHTTPSampler.query in a text editor or a script does not change the request: the arguments still hold the old body until the sampler is opened and saved in the GUI again. Generate GraphQL samplers in the GUI, or, when plans are produced by code, write the arguments too.

Switching Method to GET makes the GUI produce query-string parameters instead of a body: operationName (when set), query (with every run of whitespace collapsed to a single space) and variables (when set), each with URL Encode? on. The request line for the same operation looks like this (shortened):

GET has its place in a load test only if production clients use it: the GraphQL-over-HTTP specification makes GET support optional and conventionally restricted to queries, never mutations, and a server may not accept it at all. Its main effect is that responses become cacheable by HTTP caches and CDNs, so a GET-based test that hits a cache measures the cache. The trade-offs are explained in Serving GraphQL over HTTP.

A document can define several named operations; the server executes the one named in operationName. That lets one Query editor hold a small library, with each sampler choosing its operation:

Sending the whole document on every request costs bandwidth and server parse time, so for a load test prefer one operation per sampler and use the operation name for readability in the results. How variables, fragments and directives work on the server side is covered in Variables, Directives & Fragments.

A GraphQL server served as application/json conventionally answers 200 for every request that reached the GraphQL layer, including one whose data is null and whose errors array is full. JMeter’s default success rule (non-4xx, non-5xx) therefore counts failed operations as successes. Two JSON Assertions fix this:

The second assertion fails the sample when an errors field exists. A partial result (data plus errors) then counts as an error, which is the right default for a load test; relax it only for operations where partial results are expected. Servers that answer with application/graphql-response+json (when the client sends that Accept) also use 4xx codes for requests that fail validation; the assertions above still apply. The response shape is covered in Response and Error Handling.

Source: JSON Assertion (Component Reference)

The HTTP(S) Test Script Recorder has a Detect GraphQL Request option (in its GraphQL HTTP Sampler settings). In the 5.6.3 source, a recorded POST with an application/json content type, or a GET with GraphQL parameters, is turned into a GraphQL HTTP Request when its query starts with the keyword query or mutation; other requests stay plain HTTP Requests. Anonymous shorthand documents ({ books { id } }) are therefore not detected, and neither are documents that start with a fragment definition; those can be converted by hand. Recording itself is covered on Recording & cURL Import.

The books test SOAP with dedicated samplers. Both were removed from core JMeter:

The replacement is not a workaround; it is how the user manual builds SOAP tests today. Start from File → Templates…​ → Building a SOAP WebService Test Plan, which creates User Defined Variables, HTTP Request Defaults, a Thread Group, an HTTP Request with an envelope in Body Data, an HTTP Header Manager with Content-Type and SOAPAction, and a Response Assertion. Adjust the server in the Defaults, the path in the request, the SOAPAction header and the envelope.

Source: Building a WebService Test Plan (User Manual) and JMeter changes history (3.0 and 3.2)

Bookshelf is a REST and GraphQL service, so the example uses a hypothetical legacy catalogue service in the same stack, /soap/catalog, with the namespace urn:bookshelf:catalog:v1 and an operation GetBook. The steps are the same for any SOAP 1.1 service:

The user manual adds two practical notes: if the service returns errors, check that the envelope’s xmlns attributes match the WSDL exactly; and many non-.NET services do not use SOAPAction, in which case remove the header. For SOAP 1.2 the content type is application/soap+xml instead, with the action carried as its action parameter, as defined by the W3C SOAP 1.2 specification; check which version the WSDL binding uses.

The envelope is XML inside XML, so the .jmx stores it escaped (<, "); the GUI shows it as plain XML. A value inserted into the envelope must be XML-safe: use ${__escapeXml(${title})} for free text.

Source: Building a WebService Test Plan (User Manual), __escapeXml (Functions) and SOAP Version 1.2 Part 2 (W3C)

The XPath2 Extractor (since 5.0) reads values from XML with XPath 2.0. The component reference recommends it over the older XPath Extractor for its easier namespace handling, better performance and XPath 2.0 support.

The book title from the GetBookResponse:

Namespaces are the usual source of "nothing matched": a query without a prefix (//title) does not match an element in a namespace. Declare a prefix for every namespace used in the query. A global mapping can also be kept in a properties file named by the xpath.namespace.config property. Compiled queries are cached; the cache size is xpath2query.parser.cache.size (default 400).

Source: XPath2 Extractor (Component Reference) and Properties Reference

The XPath2 Assertion (since 5.2) checks that a document is well-formed and that an XPath expression matches; the default expression / matches any well-formed document. It also accepts boolean expressions such as count(//*error)=2.

A SOAP 1.1 service reports errors with a soap:Fault element in the body, usually with HTTP status 500, which the HTTP sampler already marks as failed. A service that returns faults with status 200, or a negative test that expects a fault, needs an explicit check. The assertion below fails the sample whenever the response contains a fault:

For a negative test that expects a fault, add first a Response Assertion on the response code with Ignore Status and the pattern 500, then an XPath2 Assertion on //soap:Fault/faultcode without Invert.

Source: XPath2 Assertion (Component Reference)

A plain Response Assertion with Substring on a closing tag (as the SOAP template does) is cheaper than an XPath2 Assertion because it does not parse the document. Use XPath when the structure matters, substring checks when a marker is enough.