Skip to content

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.

template <typename T>
RestRequest& path(const char* key, T value);

Supported types for value: int, long, float, double, bool, const char*, char*

Example:

// Produces: GET /users/15
client.get("/users/{id}")
      .path("id", 15);


query(key, value)

Appends a URL query parameter. Chainable.

template <typename T>
RestRequest& query(const char* key, T value);

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.

template <typename T>
RestRequest& body(const char* key, T value);

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() and body() 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.

template <typename T>
RestRequest& body(const T& obj);

Example:

User user = {15, "Pedro", 9.8f, true};
client.post("/users").body(user);


timeout(timeoutMs)

Sets a per-request network timeout in milliseconds, overriding the client's default timeout. Chainable.

RestRequest& timeout(uint16_t timeoutMs);

Example:

client.get("/quick-data").timeout(1500);


retry(maxRetry) / maxRetry(maxRetry)

Sets the maximum number of automatic retries on network failure for this specific request, overriding the client default. Chainable.

RestRequest& retry(int maxRetry);
RestRequest& maxRetry(int maxRetry);

Example:

client.get("/critical-data").retry(3);


onSuccess(callback)

Registers a per-request callback executed if the response HTTP status code is 2xx (200 <= code < 300). Chainable.

RestRequest& onSuccess(HttpResponseCallback cb);

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.

RestRequest& onError(HttpErrorCallback cb);
RestRequest& onError(HttpResponseCallback cb);

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.

RestRequest& onResponse(HttpResponseCallback cb);

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",   &timestamp);


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("storm").equals(true)
.filterArray("temperature").notEquals(0)

filterArray() is optional. Without it, collect() appends every element of the array:

// Response shaped as [{...}, {...}]
client.get("/forecast")
      .collect(&forecasts);

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 null field never matches, even with notEquals().
  • String filter values are limited to 63 characters.
  • A float filter value is rounded to 5 significant digits before the comparison, and the JSON number is compared as a double. Use a double for 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:

client.get("/forecast")
      .filterArray("", "data")
      .collect(&forecasts);

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*)