title: RestRequest Class Reference - Fluent Request Builder C++ Methods description: API reference for RestRequest class: method chaining for query parameters, request bodies, JSON field bindings, callbacks, and status codes. keywords: RestRequest class ESP32, fluent HTTP builder C++, getBody RestRequest, ESP32 REST API builder tags: - api - request - class
RestRequest¶
The fluent request builder returned by every HTTP method on ESP32HTTPClient. All builder methods return RestRequest&, enabling fluent chaining.
The HTTP request is dispatched automatically when the RestRequest object goes out of scope (at the end of the statement).
Copy semantics
RestRequest is move-only — it cannot be copied. It is designed to be used in a single chained expression.
Building the Request¶
path(key, value)¶
Replaces a placeholder (e.g. {id} or id) in the URL path. Chainable.
Supported types for value: int, long, float, double, bool, const char*, char*
Example:
query(key, value)¶
Appends a URL query parameter. Chainable.
Supported types for value: int, long, float, double, bool, const char*, char*
Example:
// Produces: GET /users?page=2&limit=20&search=pedro
client.get("/users")
.query("page", 2)
.query("limit", 20)
.query("search", "pedro");
body(key, value)¶
Adds a field to the JSON request body. Automatically sets Content-Type: application/json. Chainable.
Supported types for value: int, long, float, double, bool, const char*, char*
Type serialization:
| C++ Type | JSON Output Example |
|---|---|
const char* / char* |
"string value" |
int |
42 |
long |
1721156604 |
float |
24.5 (up to 5 significant digits) |
double |
3.14159265 (up to 9 significant digits) |
bool |
true or false |
Value length: values passed to
path(),query()andbody()are kept in dynamically allocated memory, so there is no fixed size limit and values are never truncated; the only limit is the available heap. This is only about storage: the JSON type is still decided by the C++ type, as shown in the table above (numbers and booleans are sent without quotes, text is sent as a string).
Example:
// Body: {"name":"Pedro","age":21,"active":true,"score":9.87}
client.post("/users")
.body("name", "Pedro")
.body("age", 21)
.body("active", true)
.body("score", 9.87f);
body(struct)¶
Serializes a C++ struct mapped with REST_JSON_MAP and sets it as the full JSON request body. Chainable.
Example:
timeout(timeoutMs)¶
Sets a per-request network timeout in milliseconds, overriding the client's default timeout. Chainable.
Example:
retry(maxRetry) / maxRetry(maxRetry)¶
Sets the maximum number of automatic retries on network failure for this specific request, overriding the client default. Chainable.
Example:
onSuccess(callback)¶
Registers a per-request callback executed if the response HTTP status code is 2xx (200 <= code < 300). Chainable.
Example:
client.get("/users")
.onSuccess([](int code) {
Serial.printf("Request succeeded with HTTP %d\n", code);
})
.getBody("id", &id);
onError(callback)¶
Registers a per-request callback executed if the request fails (code < 200 || code >= 400). Receives status code and an optional error description message. Chainable.
Example:
client.get("/users")
.onError([](int code, const char* message) {
Serial.printf("Request failed (%d): %s\n", code, message);
})
.getBody("id", &id);
onResponse(callback)¶
Registers a per-request callback executed when the request completes, regardless of success or failure. Chainable.
Example:
client.get("/users")
.onResponse([](int code) {
Serial.printf("Finished with code %d\n", code);
})
.getBody("id", &id);
Extracting the Response¶
getBody() registers a binding between a JSON key path and a target variable. If the key is not found, the target is left unchanged. All overloads are chainable.
getBody(key, target)¶
Binds a JSON response field to a local variable using type-specific overloads:
RestRequest& getBody(const char* key, int* target);
RestRequest& getBody(const char* key, long* target);
RestRequest& getBody(const char* key, float* target);
RestRequest& getBody(const char* key, double* target);
RestRequest& getBody(const char* key, bool* target);
RestRequest& getBody(const char* key, char* target, size_t maxLength);
template <size_t N> RestRequest& getBody(const char* key, char (&target)[N]);
RestRequest& getBody(const char* key, String* target);
Supported target types:
| Variable Type | Expected JSON Type | Behavior |
|---|---|---|
int* |
Integer number | Truncates decimals if present |
long* |
Integer number | Useful for Unix timestamps and large IDs |
float* |
Floating-point number | Up to 5 significant digits. Supports scientific notation (e.g. 6.02e+2, -2.5E-3) |
double* |
Floating-point number | Up to 9 significant digits. Supports scientific notation (e.g. 6.02e+2, -2.5E-3) |
bool* |
Boolean | true or false |
char*, size_t / char[N] |
String | Copies up to N-1 characters, null-terminated |
String* |
String / Object / Array | Copies value as text or raw JSON |
Example:
int count;
float temp;
bool active;
char city[64];
long timestamp;
client.get("/sensor/data")
.getBody("count", &count)
.getBody("temperature", &temp)
.getBody("active", &active)
.getBody("location", city)
.getBody("timestamp", ×tamp);
Capturing Raw JSON with String¶
Pass a String* to capture entire objects, arrays, or the complete response without deserialization:
String entireResponse;
String firstUser;
client.get("/users")
.getBody("", &entireResponse) // Captures entire response from root
.getBody("0", &firstUser); // Captures first array element as raw JSON
Memory Warning
Using String with large payloads allocates dynamically on heap. Prefer typed primitives or mapped structs where possible.
Struct Mapping with getBody(&struct)¶
Binds and populates a C++ struct mapped with REST_JSON_MAP directly from root or a nested path:
template <typename T> RestRequest& getBody(T* target);
template <typename T> RestRequest& getBody(const char* key, T* target);
Example:
User user;
UserProfile profile;
client.get("/user/1").getBody(&user);
client.get("/dashboard").getBody("data.profile", &profile);
Filtering and collecting arrays¶
Use filterArray(path) with equals() or notEquals() and collect() to keep only the objects of an array whose field matches. The path is relative to each array element and can be nested with dots.
std::vector<Weather> forecasts;
// Response shaped as [{"location": {"countryCode": "..."}}, {...}]
client.get("/forecast")
.filterArray("location.countryCode").equals("CA")
.collect(&forecasts);
collect(&vector) requires a mapped struct (REST_JSON_MAP) and appends only matching objects to the target vector. Elements that are not objects are skipped.
equals() and notEquals() accept bool, int, unsigned int, long, unsigned long, long long, unsigned long long, float, double, const char* and String.
filterArray() is optional. Without it, collect() appends every element of the array:
To capture the matching object as raw JSON instead, pass a String target:
Memory Warning
Using String with large payloads allocates dynamically on heap. Prefer typed primitives or mapped structs where possible.
String forecast;
client.get("/forecast")
.filterArray("location.countryCode").equals("CA")
.collect(&forecast);
The target contains all matching objects as a JSON array, even when the response root is a single object.
Notes and limitations
- A missing or
nullfield never matches, even withnotEquals(). - String filter values are limited to 63 characters.
- A
floatfilter value is rounded to 5 significant digits before the comparison, and the JSON number is compared as adouble. Use adoublefor an exact comparison. - If nothing matches, or if the response does not have the expected shape (for example, the array path does not exist or points to a string or number), the target stays unchanged and no error is reported.
Arrays inside an object¶
filterArray(key, arrayPath) takes the path of the array that contains the objects, arrayPath, as an optional second argument. Without it, the array is the response root. The path can be nested with dots and array indices, like the key of getBody().
// Response shaped as {"apiType": "rest", "data": [...]}
client.get("/forecast")
.filterArray("location.countryCode", "data").equals("CA")
.collect(&forecasts);
To collect every element of a nested array without filtering, use an empty key:
If the response root (or the object at arrayPath) is an object instead of an array, that object is treated as a single element.
// Response shaped as {"location": {"countryCode": "CA"}, "temperature": -2}
client.get("/forecast")
.filterArray("location.countryCode").equals("CA")
.collect(&forecasts); // forecasts.size() == 1
Extracting Response Headers¶
getHeader() registers the extraction of HTTP response headers. Header lookup is case-insensitive (e.g., "token", "TOKEN", and "Token" are equivalent). If the header is missing from the response, the target variable remains unchanged. All overloads are chainable.
getHeader(name, target)¶
RestRequest& getHeader(const char* name, String* target);
RestRequest& getHeader(const char* name, char* target, size_t maxLength);
template <size_t N> RestRequest& getHeader(const char* name, char (&target)[N]);
RestRequest& getHeader(const char* name, int* target);
RestRequest& getHeader(const char* name, long* target);
RestRequest& getHeader(const char* name, float* target);
RestRequest& getHeader(const char* name, double* target);
RestRequest& getHeader(const char* name, bool* target);
Supported target types:
| Variable Type | Header Format | Conversion / Behavior |
|---|---|---|
String* |
Text | Copies full header value |
char*, size_t / char[N] |
Text | Copies up to N-1 characters, null-terminated |
int* |
Numeric | Parsed via atoi (e.g., Content-Length) |
long* |
Numeric | Parsed via atol (e.g., X-Timestamp) |
float* |
Numeric | Parsed via strtof (e.g., X-Rate-Limit) |
double* |
Numeric | Parsed via strtod |
bool* |
Text / Boolean | true for "true" or "1", false otherwise |
Example:
String token;
char contentType[64];
int contentLength;
bool isCached;
client.get("/auth")
.getHeader("token", &token)
.getHeader("Content-Type", contentType)
.getHeader("Content-Length", &contentLength)
.getHeader("X-Cache-Hit", &isCached)
.getBody("id", &id);
Path Notation Reference¶
| Path String | What it targets |
|---|---|
"name" |
Root-level field name |
"address.city" |
Nested field: address → city |
"address.geo.lat" |
Deeply nested: address → geo → lat |
"0.name" |
First array element's name field |
"1.address.city" |
Second array element's nested city |
"" |
The entire root-level object or array (use with String*) |