Detailed configuration

Detailed configuration is provided by the RestAssuredConfig instance with which you can configure the parameters of HTTP Client as well as Redirect, Log, Encoder, Decoder, Session, ObjectMapper, Connection, SSL and ParamConfig settings. Examples:

For a specific request:

given().config(RestAssured.config().redirect(redirectConfig().followRedirects(false))). ..

or using a RequestSpecBuilder:

RequestSpecification spec = new RequestSpecBuilder().setConfig(RestAssured.config().redirect(redirectConfig().followRedirects(false))).build();

or for all requests:

RestAssured.config = config().redirect(redirectConfig().followRedirects(true).and().maxRedirects(0));

config() and newConfig() can be statically imported from io.restassured.config.RestAssuredConfig.

Encoder config

With the EncoderConfig you can specify the default content encoding charset (if it’s not specified in the content-type header) and query parameter charset for all requests. If no content charset is specified then ISO-8859-1 is used and if no query parameter charset is specified then UTF-8 is used. Usage example:

RestAssured.config = RestAssured.config().encoderConfig(encoderConfig().defaultContentCharset("US-ASCII"));

You can also specify which encoder charset to use for a specific content-type if no charset is defined explicitly for this content-type by using the defaultCharsetForContentType method in the EncoderConfig. For example:

RestAssured.config = RestAssured.config(config().encoderConfig(encoderConfig().defaultCharsetForContentType("UTF-16", "application/xml")));

This will assume UTF-16 encoding for “application/xml” content-types that does explicitly specify a charset. By default “application/json” is specified to use “UTF-8” as default content-type as this is specified by RFC4627. Before REST Assured 6.2.0 defaultCharsetForContentType also changed the default content charset for every other content type. Call defaultContentCharset(..) too if you relied on that.

Avoid adding the charset to content-type header automatically

By default REST Assured adds the charset header automatically. To disable this completely you can configure the EncoderConfig like this:

RestAssured.config = RestAssured.config(config().encoderConfig(encoderConfig().appendDefaultContentCharsetToContentTypeIfUndefined(false));

Decoder config

With the DecoderConfig you can set the default response content decoding charset for all responses. This is useful if you expect a different content charset than ISO-8859-1 (which is the default charset) and the response doesn’t define the charset in the content-type header. Usage example:

RestAssured.config = RestAssured.config().decoderConfig(decoderConfig().defaultContentCharset("UTF-8"));

You can also use the DecoderConfig to specify which content decoders to apply. When you do this the Accept-Encoding header will be added automatically to the request and the response body will be decoded automatically. By default GZIP and DEFLATE decoders are enabled. To for example to remove GZIP decoding but retain DEFLATE decoding you can do the following:

given().config(RestAssured.config().decoderConfig(decoderConfig().contentDecoders(DEFLATE))). ..

You can also specify which decoder charset to use for a specific content-type if no charset is defined explicitly for this content-type by using the “defaultCharsetForContentType” method in the DecoderConfig. For example:

RestAssured.config = config(config().decoderConfig(decoderConfig().defaultCharsetForContentType("UTF-16", "application/xml")));

This will assume UTF-16 encoding for “application/xml” content-types that does explicitly specify a charset. By default all JSON content-types use UTF-8 when the response doesn’t specify a charset, as RFC 8259 requires. This covers application/json, text/json, application/json with extra parameters (such as application/json; version=1), and since REST Assured 6.1.0 every +json type, such as application/problem+json or application/hal+json. A charset you configure with defaultCharsetForContentType takes precedence. Before REST Assured 6.2.0 defaultCharsetForContentType also changed the default content charset for every other content type. Call defaultContentCharset(..) too if you relied on that.

Session config

With the session config you can configure the default session id name that’s used by REST Assured. The default session id name is JSESSIONID and you only need to change it if the name in your application is different and you want to make use of REST Assured’s session support. Usage:

RestAssured.config = RestAssured.config().sessionConfig(new SessionConfig().sessionIdName("phpsessionid"));

Redirect DSL

Redirect configuration can also be specified using the DSL. E.g.

given().redirects().max(12).and().redirects().follow(true).when(). ..

See Redirects for which redirects REST Assured follows, how to test the redirect itself, and every redirect setting.

Connection config

Lets you configure connection settings for REST Assured. For example if you want to close the connections of the HTTP client after each response, so that each request gets a new client. You may want to do this if a server, or a proxy in between, doesn’t cope with connections that are reused. By default connections are not closed after each response, and the JDK HTTP client, the default, reuses them for the requests that follow.

RestAssured.config = RestAssured.config().connectionConfig(connectionConfig().closeIdleConnectionsAfterEachResponse());

closeIdleConnectionsAfterEachResponseAfter(idleTime, timeUnit) closes, after each response, only the connections that have been idle for longer than the idle time. It works with Apache HttpClient 5 (http-client-apache5) and httpClientConfig().reuseHttpClientInstance(). The JDK client closes idle connections after a time that it decides itself, so there it has no effect, and REST Assured logs a warning once.

JSON config

JsonPathConfig allows you to configure the Json settings either when used by REST Assured or by JsonPath. It let’s you configure how JSON numbers should be treated.

RestAssured.config = RestAssured.config().jsonConfig(jsonConfig().numberReturnType(NumberReturnType.BIG_DECIMAL))

Import NumberReturnType from io.restassured.common.config. JsonPathConfig.NumberReturnType is deprecated since REST Assured 6.3.0.

REST Assured refuses a JSON number that’s longer than 1000 characters. Nobody writes numbers like that by hand. The limit is there because turning a huge number into a BigInteger or BigDecimal can take a lot of CPU and memory, so a broken or hostile service could stall your test run. If your service really sends numbers that long, raise the limit, or turn it off with a negative value:

RestAssured.config = RestAssured.config().jsonConfig(jsonConfig().numberLengthLimit(5000));

JsonPathConfig has the same setting, for when you use JsonPath on its own.

HTTP client config

Lets you configure the HTTP client that REST Assured sends the requests with. Since REST Assured 7.0.0 that’s the JDK’s java.net.http.HttpClient by default, from the http-client-jdk module that rest-assured depends on.

To send the requests with Apache HttpClient 5 instead, which behaves more like Apache HttpClient 4 that REST Assured used before 7.0.0, add http-client-apache5 to your test dependencies:

Maven
Gradle

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>http-client-apache5</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

testImplementation 'io.rest-assured:http-client-apache5:7.0.0-RC1'

REST Assured then uses it. You can still pick the client for all requests, or for one:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig().client(HttpClientType.APACHE5));
given().config(RestAssured.config().httpClient(httpClientConfig().client(HttpClientType.JDK))). ..

or with the system property -Drestassured.http.client=jdk or -Drestassured.http.client=apache5. See The HTTP client in the release notes for how REST Assured picks the client, the versions of Apache HttpClient 5 it supports, and how the two clients differ from each other and from Apache HttpClient 4.

The JDK client is shared by all requests with the same settings, so they reuse its connections. Apache HttpClient 5 gets a new client, and so a new connection, for each request, as HttpClient 4 did. To reuse one client and its connections for the requests instead:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig().reuseHttpClientInstance());

To customize the client beyond the settings below, use the builder of its library. For the JDK client that’s java.net.http.HttpClient.Builder:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig()
        .customizeClient(java.net.http.HttpClient.Builder.class, builder -> builder.executor(executor)));

For Apache HttpClient 5 it’s org.apache.hc.client5.http.impl.classic.HttpClientBuilder:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig()
        .customizeClient(HttpClientBuilder.class, builder -> builder.addRequestInterceptorFirst(
                (request, entity, context) -> request.addHeader("X-Trace-Id", traceId))));

A customizer can’t turn on retries, redirects, cookies or decompression, since REST Assured does those itself. See Customizing the client for what each setting of HttpClientBuilder does, for example how to limit the connections.

Since REST Assured 6.3.0 you can set timeouts and other HTTP settings directly:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig()
        .connectTimeout(Duration.ofSeconds(5))
        .readTimeout(Duration.ofSeconds(10))
        .connectionRequestTimeout(Duration.ofSeconds(2)));

keepResponseCookies(true) sends the cookies a response sets in the requests that follow it, for example when a redirect is followed (by default they’re not kept). cookieDatePatterns(..) sets the date formats for reading a non-standard expires attribute of those cookies, expectContinue(true) sends Expect: 100-continue, and multipartMode(..) sets how multipart requests are encoded.

These replace the HttpClient 4 parameters, such as setParam(CoreConnectionPNames.CONNECTION_TIMEOUT, 5000), which are deprecated and removed in REST Assured 8.0.0. A parameter without a replacement fails the request. See Preparing for REST Assured 7.0 for the full list. httpClientFactory(..), which supplied your own HttpClient 4 instance, is removed in REST Assured 7.0.0.

Host header, NTLM and proxy TLS

The JDK client covers most tests, but there are a few things it can’t do. If your tests need one of these, add http-client-apache5 as shown above and they work:

Set the Host, Connection or Upgrade header yourself. A typical case is testing virtual hosts: given().header("Host", "shop.example.com").
Send an Expect header other than 100-continue.
Log in with NTLM (auth().ntlm(..)).
Talk to the proxy over TLS (ProxySpecification.withScheme("https")).

You don’t have to guess which one you hit. The request fails with an UnsupportedOperationException that says what to do, for example:

The JDK HTTP client (the default module, http-client-jdk) can't send a Host header. Add io.rest-assured:http-client-apache5
to your test dependencies and REST Assured uses it, or start the JVM with -Djdk.httpclient.allowRestrictedHeaders=host.

As the message says, for the Host, Connection and Upgrade headers you can also keep the JDK client and start the JVM with the system property jdk.httpclient.allowRestrictedHeaders. With Maven, put it in the Surefire configuration:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <argLine>-Djdk.httpclient.allowRestrictedHeaders=host</argLine>
    </configuration>
</plugin>

The property has to be set before the JDK client is first used, so setting it with System.setProperty(..) in a test usually comes too late. See JDK client limitations in the release notes for the full list.

Writing your own HTTP client

If neither the JDK client nor Apache HttpClient 5 fits, for example because you want to send the requests with OkHttp, you can plug in your own client. You implement two interfaces from io.restassured.common.spi.http in rest-assured-common: a provider that creates clients, and the client itself.

public class MyHttpClientProvider implements HttpClientProvider {
    public String name() { return "my-client"; }               // what users pick it by
    public String displayName() { return "My HTTP client"; }   // shown in messages
    public String artifact() { return "com.example:rest-assured-my-client"; }
    public String libraryDescription() { return "My HTTP client 1.2.3"; }
    public ClientSharing sharing() { return ClientSharing.SHARED; } // or PER_REQUEST
    public Class<?> builderType() { return null; }              // the builder that customizeClient(..) gets, if any

    public HttpClientInstance newClient(ClientSettings settings) {
        return new MyHttpClientInstance(settings);
    }
}

class MyHttpClientInstance implements HttpClientInstance {
    MyHttpClientInstance(ClientSettings settings) {
        // Set up your library with settings.tls(), proxy(), connectTimeout() and so on,
        // and run settings.customizers() on its builder with customizer.applyTo(builder)
    }

    public HttpResponse send(HttpRequest request) throws IOException {
        // Send request.method(), uri(), headers() and body() with your library, then return
        // the status, the headers and the body stream as they arrived
        return new HttpResponse("HTTP/1.1", statusCode, reasonPhrase, headers, contentLength, bodyStream, libraryResponse::close);
    }

    public void close() {
        // Close your library's client
    }
}

The one thing to keep in mind is that your client should send exactly the request it gets and nothing more. REST Assured follows redirects, answers authentication challenges, keeps cookies and decodes gzip itself, so your client must not do any of that, and it shouldn’t retry. If the request has a body, add its content type as a Content-Type header unless the request already has one. When connecting or waiting for the response times out, throw ConnectionTimeoutException or ResponseTimeoutException. When your library can’t do something that’s asked of it, such as NTLM, throw UnsupportedFeatureException instead of quietly doing something else. The javadoc of HttpClientInstance has the full list.

Your jar also needs two files so that REST Assured can find the provider. The first is META-INF/services/io.restassured.common.spi.http.HttpClientProvider, with the class name of your provider:

com.example.MyHttpClientProvider

The second is META-INF/rest-assured/http-client/com.example.MyHttpClientProvider.properties:

artifact=com.example:rest-assured-my-client
version=1.0.0
http-spi-revision=1

http-spi-revision is the revision of the interfaces you built against, HttpClientSpi.REVISION, which is 1 in REST Assured 7.0.0. REST Assured refuses a client built for another revision, and tells you so, rather than failing halfway through a request.

REST Assured never picks a client like this on its own, so you name it:

RestAssured.config = RestAssured.config().httpClient(httpClientConfig().client("my-client"));

client(MyHttpClientProvider.class) and -Drestassured.http.client=my-client work too. In OSGi, REST Assured finds the provider with ServiceLoader, which needs a ServiceLoader Mediator such as Apache Aries SPI Fly. For complete examples, look at http-client-jdk and http-client-apache5.

SSL config

The SSLConfig allows you to specify more advanced SSL configuration such as truststore, keystore type and host name verifier. For example:

RestAssured.config = RestAssured.config().sslConfig(sslConfig().with().keystoreType(<type>).and().strictHostnames());

Since REST Assured 6.3.0 you can also give it a javax.net.ssl.SSLContext and a javax.net.ssl.HostnameVerifier:

RestAssured.config = RestAssured.config().sslConfig(sslConfig().sslContext(sslContext).hostnameVerifier(hostnameVerifier));

Host names are still verified strictly by default when you set an SSLContext. sslSocketFactory(..) and x509HostnameVerifier(..), which took Apache HttpClient 4 types, are removed in REST Assured 7.0.0.

Param config

ParamConfig allows you to configure how different parameter types should be updated on “collision”. By default all parameters are merged so if you do:

given().queryParam("param1", "value1").queryParam("param1", "value2").when().get("/x"). ...

REST Assured will send a query string of param1=value1&param1=value2. This is not always what you want though so you can configure REST Assured to replace values instead:

given().
        config(config().paramConfig(paramConfig().queryParamsUpdateStrategy(REPLACE))).
        queryParam("param1", "value1").
        queryParam("param1", "value2").
when().
        get("/x"). ..

REST Assured will now replace param1 with value2 (since it’s written last) instead of merging them together. You can also configure the update strategy for each type of for all parameter types instead of doing it per individual basis:

given().config(config().paramConfig(paramConfig().replaceAllParameters())). ..

This is also supported in the Spring Mock Mvc Module (but the config there is called MockMvcParamConfig).

Failure config

The FailureConfig can be used to get callbacks when REST Assured validation fails. This is useful if you want to do some custom logging or store data available in the request/response specification or in the response itself somewhere. For example let’s say that you want to be notified by email when the following test case fails because the status code is not 200:

given().
    param("x", "y")
when().
    get("/hello")
then().
    statusCode(200);

You can then implement a ResponseValidationFailureListener and add it to the FailureConfig:

ResponseValidationFailureListener emailOnFailure = (reqSpec, respSpec, resp) -> emailService.sendEmail("email@gmail.com", "Important test failed! Status code was: " + resp.statusCode());

given().
    config(RestAssured.config().failureConfig(failureConfig().with().failureListeners(emailOnFailure))).
    param("x", "y")
when().
    get("/hello")
then().
    statusCode(200);

Matcher config

When a check fails, REST Assured writes its own, shorter version of the Hamcrest message. Usually that’s easier to read. But it leaves out the quotes, and sometimes the quotes are exactly what you need. Say the service returns "Jane ", with a space at the end:

JSON path name doesn't match.
Expected: Jane
  Actual: Jane

The two values look the same. The MatcherConfig can switch to the plain Hamcrest messages:

RestAssured.config = RestAssured.config().matcherConfig(matcherConfig().errorDescriptionType(HAMCREST));

and now the space is easy to spot:

JSON path name doesn't match.

Expected: "Jane"
  Actual: was "Jane "

The same goes for a number that you expected as a string. The Hamcrest message shows Expected: "1" and Actual: was <1>, so you see that the service sent the number 1 and not the text “1”. matcherConfig() and HAMCREST are statically imported from io.restassured.config.MatcherConfig and io.restassured.config.MatcherConfig.ErrorDescriptionType.

CSRF config

The CsrfConfig can be used to configure REST Assured to support CSRF. It provides more fine-grained control that is not available in the normal DSL.

given().
    config(config().csrfConfig(csrfConfig().with().csrfTokenPath("/loginPageWithCsrf").and().loggingEnabled(LogDetail.BODY))).
when().
    post("/loginPageWithCsrf").
then().
    statusCode(200);