http_request API Modernization: Vector-Based Headers

Mar 12, 2026

The http_request component’s C++ API has been updated to use std::vector instead of std::map, std::list, and std::set for header handling. The get_response_headers() method (returning the full headers map) has been removed — use get_response_header(name) instead. Deprecated overloads using the old container types are provided until 2027.1.0.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14024: Modernize response header handling PR #14027: Modernize request header handling

The http_request API used heavyweight STL containers (std::map, std::list, std::set) for header storage. These containers pull in significant template code (red-black trees, linked lists) and allocate heavily on the heap. Replacing them with std::vector<Header> reduces flash usage and heap fragmentation.

What’s Changing

Response headers (PR #14024)

Before	After
`std::map<std::string, std::list<std::string>>`	`std::vector<Header>`
`std::set<std::string>` for collect_headers	`std::vector<std::string>` (pre-lowercased)
`get_response_headers()` returns full map	Removed — use `get_response_header(name)`
`collect_headers` parameter	Renamed to `lower_case_collect_headers`
`start()` with `std::set` overload	Deprecated (removal 2027.1.0)

Request headers (PR #14027)

Before	After
`std::list<Header>` in `perform()`, `start()`, `get()`, `post()`	`std::vector<Header>`
`std::list<Header>` overloads for `start()`, `get()`, `post()`	Deprecated (removal 2027.1.0)

Who This Affects

External components that:

Use http_request APIs to make HTTP requests
Access response headers via get_response_headers()
Pass request headers as std::list<Header>
Pass collect_headers as std::set<std::string>

Standard YAML configurations are not affected.

Migration Guide

Request headers — change one word

// Before
std::list<http_request::Header> headers;
headers.push_back({"Authorization", "Bearer token"});

// After
std::vector<http_request::Header> headers;
headers.push_back({"Authorization", "Bearer token"});

Response headers — use singular getter

// Before (removed)
auto headers_map = response->get_response_headers();
auto content_type_list = headers_map["content-type"];

// After
auto value = response->get_response_header("content-type");

Collect headers — use vector with lowercase names

// Before
std::set<std::string> collect = {"Content-Type", "X-Custom"};
client->start(url, method, body, headers, collect);

// After — names must be pre-lowercased
std::vector<std::string> collect = {"content-type", "x-custom"};
client->start(url, method, body, headers, collect);

The parameter has been renamed to lower_case_collect_headers to make the lowercase requirement explicit.

Supporting Multiple ESPHome Versions

The deprecated std::list<Header> overloads compile on 2026.3.0 with warnings, so existing code continues to work during the transition. To suppress warnings:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  std::vector<http_request::Header> headers;
#else
  std::list<http_request::Header> headers;
#endif
headers.push_back({"Authorization", "Bearer token"});

For response headers, get_response_header(name) is new in 2026.3.0:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  auto value = response->get_response_header("content-type");
#else
  auto headers = response->get_response_headers();
  auto it = headers.find("content-type");
  // ...
#endif

Timeline

ESPHome 2026.3.0 (March 2026): New vector-based API active, old overloads deprecated
ESPHome 2027.1.0 (January 2027): Deprecated std::list and std::set overloads removed

Finding Code That Needs Updates

# Find std::list<Header> usage
grep -rn 'std::list.*Header' your_component/

# Find get_response_headers() (plural — removed)
grep -rn 'get_response_headers' your_component/

# Find std::set for collect_headers
grep -rn 'std::set.*collect\|collect_headers' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Comments

Feel free to leave a comment here to discuss this post with others. You can ask questions, share your experience, or suggest improvements. If you have a question about a specific feature or issue, please consider using the ESPHome Discord. Stick to English and follow ESPHome's code of conduct. These comments exist on a discussion on GitHub, so you can also comment there directly if you prefer.