Dart HttpClientRequest
last modified April 4, 2025
The HttpClientRequest class in Dart represents an HTTP client request.
It's used to configure and send HTTP requests to servers. This class provides
methods to set headers, write data, and manage the request lifecycle.
HttpClientRequest is part of Dart's dart:io library. It's created
by HttpClient when opening connections. The class supports various HTTP methods
like GET, POST, PUT, and DELETE.
Basic Definition
HttpClientRequest represents an outgoing HTTP request. It provides
access to request headers, the request body output stream, and response handling.
Key features include header manipulation, request method configuration, and stream-based body writing. It works with HttpClientResponse for complete HTTP client functionality.
Basic GET Request
This example shows how to make a simple GET request using HttpClientRequest.
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.getUrl(
Uri.parse('https://jsonplaceholder.typicode.com/posts/1')
);
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
We create an HttpClient, then use getUrl() to create a GET request. After configuring, we close the request and await the response. The response body is decoded from UTF-8.
$ dart main.dart
Status code: 200
Response body:
{
"userId": 1,
"id": 1,
"title": "...",
"body": "..."
}
POST Request with JSON Body
This example demonstrates sending a POST request with JSON data.
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.postUrl(
Uri.parse('https://jsonplaceholder.typicode.com/posts')
);
request.headers.contentType = ContentType.json;
request.write(jsonEncode({
'title': 'foo',
'body': 'bar',
'userId': 1
}));
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
We create a POST request and set the Content-Type header to application/json. The request body is written as JSON-encoded data. The server responds with the created resource representation.
$ dart main.dart
Status code: 201
Response body:
{
"title": "foo",
"body": "bar",
"userId": 1,
"id": 101
}
Setting Custom Headers
This example shows how to set custom headers on a request.
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
HttpClientRequest request = await client.getUrl(
Uri.parse('https://httpbin.org/headers')
);
request.headers.add('X-Custom-Header', 'DartClient');
request.headers.add('Accept', 'application/json');
HttpClientResponse response = await request.close();
var responseBody = await response.transform(utf8.decoder).join();
print('Status code: ${response.statusCode}');
print('Response body:\n$responseBody');
} finally {
client.close();
}
}
We add custom headers to the request using the headers property. The httpbin.org service echoes back all received headers in its response. This helps verify header transmission.
$ dart main.dart
Status code: 200
Response body:
{
"headers": {
"Accept": "application/json",
"Host": "httpbin.org",
"X-Custom-Header": "DartClient",
...
}
}
Uploading File with PUT Request
This example demonstrates uploading a file using a PUT request.
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
var file = File('example.txt');
try {
HttpClientRequest request = await client.putUrl(
Uri.parse('https://example.com/upload')
);
request.headers.contentType = ContentType.text;
request.contentLength = await file.length();
await request.addStream(file.openRead());
HttpClientResponse response = await request.close();
print('Upload complete. Status: ${response.statusCode}');
} finally {
client.close();
}
}
We create a PUT request and set the content length from the file size. The file contents are streamed directly to the request body. This approach is memory-efficient for large files.
$ dart main.dart Upload complete. Status: 200
Handling Redirects
This example shows how to configure and handle HTTP redirects.
import 'dart:io';
import 'dart:convert';
Future<void> main() async {
var client = HttpClient();
try {
client.maxRedirects = 3; // Set maximum redirects
HttpClientRequest request = await client.getUrl(
Uri.parse('http://google.com')
);
request.followRedirects = true;
HttpClientResponse response = await request.close();
print('Final status: ${response.statusCode}');
print('Redirect count: ${response.redirects.length}');
print('Final URL: ${response.redirects.last?.location}');
} finally {
client.close();
}
}
We configure the client to follow redirects and set a maximum limit. The response object contains information about all redirects that occurred. This helps debug and analyze redirect chains.
$ dart main.dart Final status: 200 Redirect count: 1 Final URL: https://www.google.com/
Best Practices
- Close requests: Always close requests with close()
- Error handling: Implement proper error handling
- Stream data: Use streams for large payloads
- Reuse clients: Reuse HttpClient instances when possible
- Set timeouts: Configure timeouts for reliability
Source
Dart HttpClientRequest Documentation
This tutorial covered Dart's HttpClientRequest class with practical examples showing various HTTP methods, headers, file uploads, and redirect handling.
Author
List all Dart tutorials.