Getting started

Not sure which modules you need? See Which module do I need.

Maven / Gradle users

Add the dependencies you need to your pom.xml or build.gradle. Pick Maven or Gradle in any of the tabs below and every page shows that one.

REST Assured

Since REST Assured 7.0.0, rest-assured doesn’t include a path engine. If your tests use paths, such as body("lotto.lottoId", equalTo(5)), path(..) or jsonPath(), also add JsonPath, and XmlPath for paths on XML and HTML. See Path engines.

Maven

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

Gradle

testImplementation 'io.rest-assured:rest-assured:7.0.0-RC1'

Notes

1. You should place rest-assured before the JUnit dependency declaration in your pom.xml / build.gradle in order to make sure that the correct version of Hamcrest is used.
2. Before 7.0.0, REST Assured includes JsonPath and XmlPath as transitive dependencies
3. rest-assured brings the JDK HTTP client module, http-client-jdk, which sends the requests. See Apache HttpClient 5 for the other client.

JsonPath

JsonPath, GPath for JSON. REST Assured uses it to evaluate paths on JSON bodies, and it makes it easy to parse JSON documents on its own. Called json-path before 7.0.0. Note that this JsonPath implementation uses Groovy’s GPath syntax and is not to be confused with Kalle Stenflo’s JsonPath implementation.

Maven

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>json-path-gpath</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:json-path-gpath:7.0.0-RC1'

XmlPath

XmlPath, GPath for XML and HTML. REST Assured uses it to evaluate paths on XML and HTML bodies, and it makes it easy to parse XML documents on its own. Called xml-path before 7.0.0.

Maven

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>xml-path-gpath</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:xml-path-gpath:7.0.0-RC1'

JSONPath with Jayway

Since REST Assured 7.0.0, you can write JSON paths in JSONPath, such as $.store.book[?(@.price < 10)].title, evaluated by Jayway JsonPath, instead of GPath. It’s for JSON only and doesn’t need Groovy. See JSONPath with Jayway.

Maven

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>json-path-jayway</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:json-path-jayway:7.0.0-RC1'

Apache HttpClient 5

Since REST Assured 7.0.0, REST Assured sends the requests with the JDK’s HTTP client. Add http-client-apache5 to send them with Apache HttpClient 5 instead, for example for NTLM authentication or the Host header, which the JDK client can’t send. REST Assured uses it when it’s on the classpath. See The HTTP client.

Maven

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

Gradle

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

JSON Schema validation

If you want to validate that a JSON response conforms to a Json Schema you can use the json-schema-validator module:

Maven

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>json-schema-validator</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:json-schema-validator:7.0.0-RC1'

Since REST Assured 7.0.0, the module brings Jackson 3. To validate draft-03 schemas or use a JsonSchemaFactory, also add com.github.java-json-tools:json-schema-validator, see The java-json-tools validator.

Refer to the documentation for more info.

Spring Mock Mvc

If you’re using Spring Mvc you can now unit test your controllers using the RestAssuredMockMvc API in the spring-mock-mvc module. For this to work you need to depend on the spring-mock-mvc module:

Maven

<dependency>
      <groupId>io.rest-assured</groupId>
      <artifactId>spring-mock-mvc</artifactId>
      <version>7.0.0-RC1</version>
      <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:spring-mock-mvc:7.0.0-RC1'

Using Kotlin? Refer to the documentation for Kotlin extension functions that makes it nicer to work with the Spring Mock Mvc module.

Spring Web Test Client

If you’re using Spring Webflux you can now unit test your reactive controllers using the RestAssuredWebTestClient API in the spring-web-test-client module. For this to work you need to depend on the spring-web-test-client module:

Maven

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

Gradle

testImplementation 'io.rest-assured:spring-web-test-client:7.0.0-RC1'

Scala support

If you’re using Scala you may leverage the scala-support module. For this to work you need to depend on the scala-support module:

SBT:

libraryDependencies += "io.rest-assured" % "scala-support" % "7.0.0-RC1"

Maven

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>scala-support</artifactId>
    <version>7.0.0-RC1</version>
    <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:scala-support:7.0.0-RC1'

For Scala 3, use the scala-extensions module instead.

Kotlin

If you’re using Kotlin then it’s highly recommended to use the Kotlin Extension Module. This modules provides some useful extension functions when working with REST Assured from Kotlin.

Maven

<dependency>
    <groupId>io.rest-assured</groupId>
    <artifactId>kotlin-extensions</artifactId>
    <version>7.0.0-RC1</version>
    <scope>test</scope>
</dependency>

Gradle

testImplementation 'io.rest-assured:kotlin-extensions:7.0.0-RC1'

Then import Given from the io.restassured.module.kotlin.extensions package.

If you’re using the Spring MockMvc module see Kotlin extension module for Spring MockMvc for how to use custom Kotlin extension functions for this module.

BOM

To keep all REST Assured modules on the same version, import rest-assured-bom and leave the versions out of the REST Assured dependencies:

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured-bom</artifactId>
            <version>7.0.0-RC1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle

testImplementation platform('io.rest-assured:rest-assured-bom:7.0.0-RC1')

With Spring Boot 3, set the rest-assured.version property instead. See Keep the versions in line and Spring Boot.

Java 9

If the Java module system gives you split package problems with json-path-gpath and xml-path-gpath, you can depend on rest-assured-all instead of them. It contains rest-assured-common, json-path-gpath and xml-path-gpath in one jar, and depends on Groovy. It doesn’t contain rest-assured, so keep that dependency:

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

Non-maven users

Every REST Assured module is on Maven Central. REST Assured no longer publishes distribution zip files. Use a build tool such as Maven or Gradle, which also downloads the dependencies of each module, or download the jars and their dependencies from Maven Central yourself and put them on your class path. See Downloads.

Static imports

In order to use REST assured effectively it’s recommended to statically import methods from the following classes:

io.restassured.RestAssured.*
io.restassured.matcher.RestAssuredMatchers.*
org.hamcrest.Matchers.*

If you want to use Json Schema validation you should also statically import these methods:

io.restassured.module.jsv.JsonSchemaValidator.*

Refer to Json Schema Validation section for more info.

If you’re using Spring MVC you can use the spring-mock-mvc module to unit test your Spring Controllers using the Rest Assured DSL. To do this statically import the methods from RestAssuredMockMvc instead of importing the methods from io.rest-assured.RestAssured and io.rest-assured.matcher.RestAssuredMatchers:

io.restassured.module.mockmvc.RestAssuredMockMvc.*
io.restassured.matcher.RestAssuredMatchers.*

Version 2.x

If you need to depend on an older version replace groupId io.rest-assured with com.jayway.restassured.

Documentation

When you’ve successfully downloaded and configured REST Assured in your classpath please refer to the usage guide for examples.

Downloads

Every REST Assured module is on Maven Central, under the group id io.rest-assured: search Maven Central, or browse the repository.

Use a build tool such as Maven or Gradle, see Getting Started and Which module do I need. It also downloads the dependencies of each module, which you otherwise download yourself and put on your class path next to the REST Assured jars.

REST Assured no longer publishes distribution zip files, and Bintray, where they were, has shut down.

Legacy versions

Versions 2.2.0 and older are in the Google Code archive.