REST Assured

REST Assured is a Java library for testing HTTP/REST APIs. You write one fluent chain: given() sets up the request (headers, body, params, auth), when() fires the HTTP call (get/post/put/delete), then() asserts on the response (status, headers, body values).

Use then().body(path, matcher). The path is a GPath expression — user.address.city, items[0].id, items.size(), items.name — and the matcher is Hamcrest (equalTo, hasItems, containsInAnyOrder). Use rootPath to avoid repeating a prefix, and matchesJsonSchemaInClasspath for whole-payload shape.

given().auth() offers basic, preemptive basic, digest, form, OAuth 1/2 and certificate auth. preemptive().basic() sends the Authorization header on the first request; plain basic() waits for a 401 challenge before resending with credentials — so it costs an extra round trip and fails against servers that never challenge.

End the chain with .extract(). Use extract().path("id") for a single GPath value, extract().response() for the whole Response (status, headers, body, time), or extract().as(User.class) to deserialize into a POJO. Then pass the value into the next given().

Build shared RequestSpecification and ResponseSpecification objects with RequestSpecBuilder/ResponseSpecBuilder and apply them with given().spec(...) / then().spec(...). For diagnostics, add log().ifValidationFails() on both request and response, or enableLoggingOfRequestAndResponseIfValidationFails(), and use Filters for cross-cutting concerns like tokens and correlation ids.

REST Assured builds the target URL by joining baseUri, then basePath, then the path given to the verb. Exactly one slash is inserted between the parts. Both methods override the matching static field for that single request only.

Passing a File alone attaches one part under MultiPartConfig's default control name, file, using the file's own name as the filename. Its part type defaults to application/octet-stream. REST Assured also sets the request Content-Type to multipart/form-data by itself.

REST Assured appends its default port of 8080 only when the target carries no port and its authority is exactly localhost. An explicitly set port always wins over it, and an https target with no port set stays on 443.

All four store the argument verbatim as the request body; no object mapper runs. They differ in the Content-Type REST Assured picks when none is set. A byte array or stream gives application/octet-stream, a String or File text/plain.

Both values are sent. REST Assured merges same-name parameters by default, producing zone=north&zone=south. To make the last call win, set ParamConfig's queryParamsUpdateStrategy to UpdateStrategy.REPLACE, or use replaceAllParameters().

REST Assured attaches a built RequestSpecification with given().spec(reqSpec), and a built ResponseSpecification with then().spec(respSpec). The static given(reqSpec, respSpec) binds both at once, returning a RequestSender on which only an HTTP verb may follow. Each takes effect where you call it.

REST Assured keeps suite-wide defaults as public static fields on its RestAssured class: baseURI, port, basePath, authentication, config, requestSpecification, responseSpecification, rootPath, urlEncodingEnabled, defaultParser, sessionId and proxy. Default filters are registered through the static filters method instead.

Chain RequestSpecBuilder setters such as setBaseUri, setBasePath, addHeader and setContentType, then call build() once to obtain a RequestSpecification. Hold that object in a static field so every case starts from it instead of repeating the depot address and headers.

RestAssured.reset() restores baseURI, basePath, rootPath, authentication and urlEncodingEnabled to their constants. It nulls requestSpecification, responseSpecification, defaultParser, sessionId and proxy, empties the filter list, drops parser registrations, installs a fresh RestAssuredConfig, and sets port to UNDEFINED_PORT (-1), not 8080.

REST Assured reads a built request specification back through SpecificationQuerier.query(spec), which returns a QueryableRequestSpecification. That read-only view exposes getters such as getBaseUri, getBasePath, getHeaders, getCookies and getDefinedFilters. No request is sent, so it runs in a plain unit test.

REST Assured's then() block asserts headers with header(name, expectedValue) for an exact string, header(name, Matcher) for anything looser, and headers(Map) for several at once. Content-Type has its own method, contentType(ContentType.JSON). A failed check throws AssertionError and prints every header received.

REST Assured validates only when at least one expectation exists. A call with no then() block, or a then() that sets no status, status line, body, header, cookie, content type or time check, returns the response and never fails.

REST Assured's body(path, matcher) evaluates the path against the parsed response body and hands the extracted value to the matcher. The no-path body(matcher) form applies the matcher to the whole raw body string instead. Both accept any Hamcrest matcher.

Nothing after the failing check runs. REST Assured validates each then() expectation the moment you call it, so a failed status assertion throws an AssertionError there and then; extract() is never reached and your local variable is never assigned.

The last one. REST Assured's header assertion reads Headers.getValue(name), which scans the response headers in reverse and returns the final case-insensitive match, so earlier occurrences are never matched. Extract headers().getValues(name) to assert on every value the response carried.

REST Assured's schema matcher ships in a separate artifact, io.rest-assured:json-schema-validator, declared alongside rest-assured. Statically import matchesJsonSchemaInClasspath from io.restassured.module.jsv.JsonSchemaValidator and pass it to the no-path body() overload. It validates the entire response body as one assertion, not a single field.

REST Assured reads a JSON array into a typed list with as(new TypeRef<List<ScaffoldInspection>>() {}); the anonymous subclass carries the element type past erasure. as(List.class) cannot, and hands back raw maps that fail on first use. Import it from io.restassured.common.mapper.

REST Assured picks a deserializer from the response content type, and text/plain matches neither JSON nor XML, so as() throws IllegalStateException. Register the type with RestAssured.registerParser, set RestAssured.defaultParser, or name a mapper with as(Class, ObjectMapperType) to bypass the decision.

A schema handed to matchesXsd as a string or stream carries no base location, so a relative xsd:import or xsd:include cannot be found. Chain using(LSResourceResolver) or with(LSResourceResolver) on the returned XmlXsdMatcher and resolve each referenced file yourself.

The classpath lookup returned nothing. matchesJsonSchemaInClasspath resolves its argument with the thread context class loader's getResource, and a miss yields null, which the matcher factory rejects immediately. Nothing was validated, so this is a wiring bug, not a schema mismatch.

Assign a scheme to the static field RestAssured.authentication, for example RestAssured.basic(user, pass). It applies to any request that sets no scheme of its own. A single request opts out with given().auth().none().

Read the session id off the login response with sessionId(), then hand it to the next call as given().sessionId(value). REST Assured writes it as the JSESSIONID cookie. One SessionFilter instance added to both requests does that capture-and-replay for you automatically.

Use given().auth().oauth2(token) - REST Assured has no bearer method at all. With the default HEADER signature that call installs a PreemptiveOAuth2HeaderScheme, which writes a plain Authorization: Bearer header on the request, with no signing and no challenge round trip.

REST Assured GETs that path and scans the HTML. By default it prefers a meta tag named _csrf_header and sends the value as the X-CSRF-TOKEN header. Otherwise it uses the hidden input named _csrf as a form parameter.

auth().basic(user, pass) installs a BasicAuthScheme that hands the credentials to the underlying Apache HttpClient, so the Authorization header goes out only after a 401. auth().preemptive().basic(...) installs no scheme at all and writes the header directly.

REST Assured buffers the log instead of printing it when you chain given().log().ifValidationFails() on the request or then().log().ifValidationFails() on the response. The buffered text reaches the console only if a then() expectation fails. RestAssured.enableLoggingOfRequestAndResponseIfValidationFails() switches both sides on globally.

REST Assured narrows log output instead of printing everything: body(), headers() and cookies() exist on both sides, method(), uri() and params() only on the request, status() only on the response. Each call registers its own logging filter.

Return a new Response built with ResponseBuilder: clone the response that ctx.next handed back, override the body, headers or status code, then build. REST Assured validates whatever your filter returns, so the rebuilt copy is what then() and extract() see.

Make each filter implement OrderedFilter and return a getOrder value; REST Assured sorts the whole filter list by that number before sending, lowest first. A plain Filter counts as DEFAULT_PRECEDENCE, one thousand, so give the earlier filter a smaller order.

REST Assured ships seven ready-made filters: RequestLoggingFilter, ResponseLoggingFilter, ErrorLoggingFilter, StatusCodeBasedLoggingFilter, TimingFilter, CookieFilter and SessionFilter. Four of them print, one records elapsed time, and two remember state between calls. Register one with given().filter(...), or on every call through RestAssured.filters(...).

RestAssuredConfig applies at three scopes: assign it to the static RestAssured.config field for every request, pass it to RequestSpecBuilder.setConfig for one reusable specification, or hand it to given().config for a single call. A narrower scope overrides a wider one.

REST Assured has no retry, no polling and no timeout method on its request DSL. You write the waiting yourself, in a bounded loop or a library such as Awaitility, and REST Assured supplies each call and the final assertion.

RestAssuredConfig.config() is a factory returning a brand-new, all-default config; RestAssured.config() returns whatever is currently assigned to the static field. Building from the factory silently discards earlier settings, because each setter copies the other seventeen objects forward unchanged.

REST Assured throws a plain java.lang.AssertionError whose message opens with a count of failed expectations and lists each mismatch. Nothing catches it, so it unwinds out of the test method and the runner that called that method records a failure.

Because REST Assured validation is not a boolean: a failed expectation throws AssertionError. Using it as a loop condition means catching AssertionError every iteration, which silently swallows real failures as not-ready-yet and ends with a timeout message naming nothing.