0
# REST Assured
1

2
REST Assured is a comprehensive Java library that provides a domain-specific language (DSL) for testing and validating REST web services. It brings the simplicity of dynamic languages like Ruby and Groovy to Java, making REST service testing more accessible and readable with fluent API syntax and powerful assertion capabilities.
3

4
## Package Information
5

6
- **Package Name**: rest-assured
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.rest-assured
10
- **Artifact ID**: rest-assured
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>io.rest-assured</groupId>
15
    <artifactId>rest-assured</artifactId>
16
    <version>5.5.2</version>
17
    <scope>test</scope>
18
  </dependency>
19
  ```
20

21
## Core Imports
22

23
```java
24
import static io.restassured.RestAssured.*;
25
import static io.restassured.matcher.RestAssuredMatchers.*;
26
import static org.hamcrest.Matchers.*;
27
```
28

29
For specific classes:
30

31
```java
32
import io.restassured.RestAssured;
33
import io.restassured.response.Response;
34
import io.restassured.specification.RequestSpecification;
35
import io.restassured.specification.ResponseSpecification;
36
import io.restassured.builder.RequestSpecBuilder;
37
import io.restassured.builder.ResponseSpecBuilder;
38
```
39

40
## Basic Usage
41

42
```java
43
import static io.restassured.RestAssured.*;
44
import static org.hamcrest.Matchers.*;
45

46
// Simple GET request with assertion
47
get("/users/1").then()
48
    .statusCode(200)
49
    .body("name", equalTo("John Doe"));
50

51
// POST request with JSON body
52
given()
53
    .contentType("application/json")
54
    .body("{\"name\":\"Jane\",\"email\":\"jane@example.com\"}")
55
.when()
56
    .post("/users")
57
.then()
58
    .statusCode(201)
59
    .body("id", notNullValue());
60

61
// Configuration and fluent API
62
RestAssured.baseURI = "https://api.example.com";
63
RestAssured.port = 443;
64

65
given()
66
    .auth().basic("username", "password")
67
    .header("Accept", "application/json")
68
    .queryParam("limit", 10)
69
.when()
70
    .get("/api/users")
71
.then()
72
    .statusCode(200)
73
    .body("users.size()", greaterThan(0))
74
    .body("users[0].name", containsString("John"));
75
```
76

77
## Architecture
78

79
REST Assured is built around several key components:
80

81
- **Static API**: `RestAssured` class providing static methods for common HTTP operations and global configuration
82
- **Fluent Interface**: Chain-able specification pattern using `given().when().then()` for readable test construction
83
- **Request Specifications**: `RequestSpecification` interface for configuring HTTP requests (headers, body, auth, etc.)
84
- **Response Specifications**: `ResponseSpecification` interface for defining expected response characteristics
85
- **Builder Pattern**: `RequestSpecBuilder` and `ResponseSpecBuilder` for creating reusable specifications
86
- **Filter System**: Extensible filter mechanism for request/response processing and custom behavior
87
- **Object Mapping**: Integration with Jackson, Gson, and JAXB for automatic JSON/XML serialization
88
- **Matcher Integration**: Deep integration with Hamcrest matchers for powerful assertions
89

90
## Capabilities
91

92
### HTTP Operations
93

94
Core HTTP request methods with path parameters, query parameters, and various response handling options.
95

96
```java { .api }
97
// Static methods for immediate requests
98
static Response get(String path, Object... pathParams);
99
static Response post(String path, Object... pathParams);
100
static Response put(String path, Object... pathParams);
101
static Response delete(String path, Object... pathParams);
102
static Response head(String path, Object... pathParams);
103
static Response patch(String path, Object... pathParams);
104
static Response options(String path, Object... pathParams);
105

106
// Custom HTTP methods
107
static Response request(Method method, String path, Object... pathParams);
108
static Response request(String method, String path, Object... pathParams);
109
```
110

111
[HTTP Operations](./http-operations.md)
112

113
### Request Building
114

115
Fluent API for constructing HTTP requests with headers, parameters, body content, authentication, and configuration.
116

117
```java { .api }
118
// Entry points for request building
119
static RequestSpecification given();
120
static RequestSpecification with();
121
static RequestSender when();
122

123
interface RequestSpecification {
124
    // Body methods
125
    RequestSpecification body(String body);
126
    RequestSpecification body(Object object);
127
    RequestSpecification body(File file);
128
    
129
    // Parameter methods
130
    RequestSpecification param(String parameterName, Object... parameterValues);
131
    RequestSpecification queryParam(String parameterName, Object... parameterValues);
132
    RequestSpecification formParam(String parameterName, Object... parameterValues);
133
    RequestSpecification pathParam(String parameterName, Object parameterValue);
134
    
135
    // Header and cookie methods
136
    RequestSpecification header(String headerName, Object headerValue);
137
    RequestSpecification cookie(String cookieName, Object cookieValue);
138
    
139
    // Content type and authentication
140
    RequestSpecification contentType(ContentType contentType);
141
    RequestSpecification auth();
142
}
143
```
144

145
[Request Building](./request-building.md)
146

147
### Response Validation
148

149
Comprehensive response validation including status codes, headers, cookies, body content, and custom matchers.
150

151
```java { .api }
152
// Response validation entry point
153
static ResponseSpecification expect();
154

155
interface ResponseSpecification {
156
    // Status validation
157
    ResponseSpecification statusCode(int expectedStatusCode);
158
    ResponseSpecification statusLine(String expectedStatusLine);
159
    
160
    // Body validation
161
    ResponseSpecification body(String path, Matcher<?> matcher);
162
    ResponseSpecification body(String path, Matcher<?> matcher, Object... additionalKeyMatcherPairs);
163
    
164
    // Header and cookie validation
165
    ResponseSpecification header(String headerName, Matcher<?> expectedValueMatcher);
166
    ResponseSpecification cookie(String cookieName, Matcher<?> expectedValueMatcher);
167
}
168

169
interface ValidatableResponse {
170
    ValidatableResponse statusCode(int expectedStatusCode);
171
    ValidatableResponse body(String path, Matcher<?> matcher);
172
    ValidatableResponse header(String headerName, Matcher<?> expectedValueMatcher);
173
    ExtractableResponse<Response> extract();
174
}
175
```
176

177
[Response Validation](./response-validation.md)
178

179
### Authentication
180

181
Support for multiple authentication schemes including basic, digest, OAuth, certificate-based, and form authentication.
182

183
```java { .api }
184
// Authentication schemes
185
static AuthenticationScheme basic(String userName, String password);
186
static AuthenticationScheme digest(String userName, String password);
187
static AuthenticationScheme oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
188
static AuthenticationScheme oauth2(String accessToken);
189
static AuthenticationScheme certificate(String certURL, String password);
190
static AuthenticationScheme form(String userName, String password);
191
static PreemptiveAuthProvider preemptive();
192

193
interface AuthenticationSpecification {
194
    RequestSpecification basic(String userName, String password);
195
    RequestSpecification digest(String userName, String password);
196
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
197
    RequestSpecification oauth2(String accessToken);
198
    RequestSpecification certificate(String certURL, String password);
199
    RequestSpecification form(String userName, String password);
200
    RequestSpecification none();
201
}
202
```
203

204
[Authentication](./authentication.md)
205

206
### Configuration
207

208
Extensive configuration options for HTTP client behavior, SSL settings, logging, object mapping, and global defaults.
209

210
```java { .api }
211
// Global configuration fields
212
static String baseURI;
213
static int port;
214
static String basePath;
215
static AuthenticationScheme authentication;
216
static RestAssuredConfig config;
217
static RequestSpecification requestSpecification;
218
static ResponseSpecification responseSpecification;
219

220
// Configuration methods
221
static void reset();
222
static void useRelaxedHTTPSValidation();
223
static void keyStore(String pathToJks, String password);
224
static void trustStore(String pathToJks, String password);
225
static void proxy(String host, int port);
226

227
class RestAssuredConfig {
228
    SSLConfig getSSLConfig();
229
    HttpClientConfig getHttpClientConfig();
230
    LogConfig getLogConfig();
231
    ObjectMapperConfig getObjectMapperConfig();
232
    JsonConfig getJsonConfig();
233
    XmlConfig getXmlConfig();
234
}
235
```
236

237
[Configuration](./configuration.md)
238

239
### Object Mapping
240

241
Automatic serialization and deserialization of Java objects to/from JSON and XML using Jackson, Gson, or JAXB.
242

243
```java { .api }
244
// Object mapping in requests
245
RequestSpecification body(Object object);
246

247
// Object mapping in responses  
248
<T> T as(Class<T> cls);
249
<T> T as(TypeRef<T> typeRef);
250

251
// Object mapper configuration
252
enum ObjectMapperType {
253
    JACKSON_1, JACKSON_2, GSON, JAXB
254
}
255

256
interface ObjectMapper {
257
    Object serialize(ObjectMapperSerializationContext context);
258
    <T> T deserialize(ObjectMapperDeserializationContext context);
259
}
260
```
261

262
[Object Mapping](./object-mapping.md)
263

264
### Filters and Extensions
265

266
Extensible filter system for request/response processing, logging, timing, and custom behavior injection.
267

268
```java { .api }
269
interface Filter {
270
    Response filter(FilterableRequestSpecification requestSpec, 
271
                   FilterableResponseSpecification responseSpec, 
272
                   FilterContext ctx);
273
}
274

275
// Built-in filters
276
class RequestLoggingFilter implements Filter;
277
class ResponseLoggingFilter implements Filter;
278
class SessionFilter implements Filter;
279
class CookieFilter implements Filter;
280

281
// Filter configuration
282
RequestSpecification filter(Filter filter);
283
static void filters(Filter filter, Filter... additionalFilters);
284
```
285

286
[Filters and Extensions](./filters-extensions.md)
287

288
## Types
289

290
```java { .api }
291
// Core response interface
292
interface Response extends ResponseBody<Response>, ResponseOptions<Response>, 
293
                          Validatable<ValidatableResponse, Response> {
294
    int getStatusCode();
295
    String getStatusLine();
296
    Headers getHeaders();
297
    Cookies getCookies();
298
    String getContentType();
299
    long getTime();
300
}
301

302
// HTTP method enumeration
303
enum Method {
304
    GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS, TRACE
305
}
306

307
// Content type enumeration with common MIME types
308
enum ContentType {
309
    JSON("application/json"),
310
    XML("application/xml"),
311
    HTML("text/html"),
312
    TEXT("text/plain"),
313
    URLENC("application/x-www-form-urlencoded"),
314
    MULTIPART("multipart/form-data");
315
}
316

317
// HTTP headers and cookies collections
318
class Headers implements Iterable<Header> {
319
    Header get(String name);
320
    List<Header> getList(String name);
321
    boolean hasHeaderWithName(String name);
322
}
323

324
class Cookies implements Iterable<Cookie> {
325
    Cookie get(String name);
326
    boolean hasCookieWithName(String name);
327
}
328

329
// Header and cookie individual representations
330
class Header {
331
    String getName();
332
    String getValue();
333
}
334

335
class Cookie {
336
    String getName();
337
    String getValue();
338
    String getDomain();
339
    String getPath();
340
    Date getExpiryDate();
341
    boolean isSecured();
342
    boolean isHttpOnly();
343
}
344
```