HttpClient class
A client that receives content, such as web pages, from a server using the HTTP protocol.
HttpClient contains a number of methods to send an HttpClientRequest to an Http server and receive an HttpClientResponse back. For example, you can use the get, getUrl, post, and postUrl methods for GET and POST requests, respectively.
Making a simple GET request: an example
A getUrl
request is a two-step process, triggered by two Futures.
When the first future completes with a HttpClientRequest, the underlying
network connection has been established, but no data has been sent.
In the callback function for the first future, the HTTP headers and body
can be set on the request. Either the first write to the request object
or a call to close sends the request to the server.
When the HTTP response is received from the server, the second future, which is returned by close, completes with an HttpClientResponse object. This object provides access to the headers and body of the response. The body is available as a stream implemented by HttpClientResponse. If a body is present, it must be read. Otherwise, it leads to resource leaks. Consider using HttpClientResponse.drain if the body is unused.
HttpClient client = new HttpClient();
client.getUrl(Uri.parse("http://www.example.com/"))
.then((HttpClientRequest request) {
// Optionally set up headers...
// Optionally write to the request object...
// Then call close.
...
return request.close();
})
.then((HttpClientResponse response) {
// Process the response.
...
});
The future for HttpClientRequest is created by methods such as getUrl and open.
HTTPS connections
An HttpClient can make HTTPS requests, connecting to a server using the TLS (SSL) secure networking protocol. Calling getUrl with an https: scheme will work automatically, if the server's certificate is signed by a root CA (certificate authority) on the default list of well-known trusted CAs, compiled by Mozilla.
To add a custom trusted certificate authority, or to send a client
certificate to servers that request one, pass a SecurityContext object
as the optional context
argument to the HttpClient
constructor.
The desired security options can be set on the SecurityContext object.
Headers
All HttpClient requests set the following header by default:
Accept-Encoding: gzip
This allows the HTTP server to use gzip compression for the body if
possible. If this behavior is not desired set the
Accept-Encoding
header to something else.
To turn off gzip compression of the response, clear this header:
request.headers.removeAll(HttpHeaders.acceptEncodingHeader)
Closing the HttpClient
The HttpClient supports persistent connections and caches network connections to reuse them for multiple requests whenever possible. This means that network connections can be kept open for some time after a request has completed. Use HttpClient.close to force the HttpClient object to shut down and to close the idle network connections.
Turning proxies on and off
By default the HttpClient uses the proxy configuration available
from the environment, see findProxyFromEnvironment. To turn off
the use of proxies set the findProxy property to
null
.
HttpClient client = new HttpClient();
client.findProxy = null;
Constructors
- HttpClient({SecurityContext context })
-
factory
Properties
-
authenticate
← Future<
bool> Function(Uri, String String) -
Sets the function to be called when a site is requesting
authentication. The URL requested and the security realm from the
server are passed in the arguments
url
andrealm
. [...]write-only -
authenticateProxy
← Future<
bool> Function(String int, String String) -
Sets the function to be called when a proxy is requesting
authentication. Information on the proxy in use and the security
realm for the authentication are passed in the arguments
host
,port
andrealm
. [...]write-only - autoUncompress ↔ bool
-
Gets and sets whether the body of a response will be automatically
uncompressed. [...]
read / write
- badCertificateCallback ← bool Function(X509Certificate, String, int)
-
Sets a callback that will decide whether to accept a secure connection
with a server certificate that cannot be authenticated by any of our
trusted root certificates. [...]
write-only
- connectionTimeout ↔ Duration
-
Gets and sets the connection timeout. [...]
read / write
- findProxy ← String Function(Uri)
-
Sets the function used to resolve the proxy server to be used for
opening a HTTP connection to the specified
url
. If this function is not set, direct connections will always be used. [...]write-only - idleTimeout ↔ Duration
-
Gets and sets the idle timeout of non-active persistent (keep-alive)
connections. [...]
read / write
- maxConnectionsPerHost ↔ int
-
Gets and sets the maximum number of live connections, to a single host. [...]
read / write
- userAgent ↔ String
-
Gets and sets the default value of the
User-Agent
header for all requests generated by this HttpClient. [...]read / write - hashCode → int
-
The hash code for this object. [...]
read-only, inherited
- runtimeType → Type
-
A representation of the runtime type of the object.
read-only, inherited
Methods
-
addCredentials(
Uri url, String realm, HttpClientCredentials credentials) → void - Add credentials to be used for authorizing HTTP requests.
-
addProxyCredentials(
String host, int port, String realm, HttpClientCredentials credentials) → void - Add credentials to be used for authorizing HTTP proxies.
-
close(
{bool force: false }) → void - Shuts down the HTTP client. [...]
-
delete(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the DELETE method. [...]
-
deleteUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the DELETE method. [...]
-
get(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the GET method. [...]
-
getUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the GET method. [...]
-
head(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the HEAD method. [...]
-
headUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the HEAD method. [...]
-
open(
String method String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection. [...]
-
openUrl(
String method, Uri url) → Future< HttpClientRequest> - Opens a HTTP connection. [...]
-
patch(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the PATCH method. [...]
-
patchUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the PATCH method. [...]
-
post(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the POST method. [...]
-
postUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the POST method. [...]
-
put(
String host int port, String path) → Future< HttpClientRequest> - Opens a HTTP connection using the PUT method. [...]
-
putUrl(
Uri url) → Future< HttpClientRequest> - Opens a HTTP connection using the PUT method. [...]
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed. [...]
inherited
-
toString(
) → String -
Returns a string representation of this object.
inherited
Operators
-
operator ==(
dynamic other) → bool -
The equality operator. [...]
inherited
Static Properties
- enableTimelineLogging ↔ bool
-
Current state of HTTP request logging from all HttpClients to the
developer timeline. [...]
read / write
Static Methods
Constants
- DEFAULT_HTTP_PORT → const int
-
@Deprecated("Use defaultHttpPort instead")
defaultHttpPort
- DEFAULT_HTTPS_PORT → const int
-
@Deprecated("Use defaultHttpsPort instead")
defaultHttpsPort
- defaultHttpPort → const int
-
80
- defaultHttpsPort → const int
-
443