# Titanium.Network.HTTPClient > HTTP client object that (mostly) implements the XMLHttpRequest specification. - Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Network.HTTPClient - Titanium SDK version: 12.6.3 - Kind: proxy - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.1 - Extends: Titanium.Proxy - Inheritance: Titanium.Proxy Use [Titanium.Network.createHTTPClient](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#createHTTPClient) to create a new `HTTPClient` object. An `HTTPClient` object is intended to be used for a single request. It may be possible to re-use an `HTTPClient` object, but this use case is not tested. There are three steps in making a typical HTTP request: * Creating an `HTTPClient` object. * Opening the `HTTPClient` object. * Sending the request. Before opening the request, you must define one or more callbacks to handle the HTTP response, as well as errors, progress updates, and other conditions. The `HTTPClient` callbacks operate somewhat differently from other Titanium callbacks, in accordance with the XMLHttpRequest specification. When the callbacks are invoked, the `this` value is set to either the original `HTTPClient` object itself, or a response object that holds all of the response-related properties defined for the `HTTPClient` object. So the callbacks can use code like this to access the response values: ``` js httpResponse = this.responseText; status = this.status; ``` #### Content-Type Header When sending a POST request with the HTTP client, the Content-Type header is set automatically depending on the platform and data type sent. On the Android and iOS platforms: * If you are sending a JavaScript object, the content type is set to `multipart/form-data`. * For all other data types on Android, the content type is set to `application/x-www-form-urlencoded`. * For all other data types on iOS, the content type is **NOT** set. Use the [setRequestHeader](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#setRequestHeader) method to override the default Content-Type header. #### Asynchronous vs. Synchronous HTTP Requests By default, the `HTTPClient` makes asynchronous requests. Asynchronous requests do not block the application and use callbacks to process responses when they are received. Synchronous requests block the execution of the application until it receives a response. On the iOS platform, you can make synchronous requests by setting the optional `async` parameter to `false` when calling the [open](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#open) method. The Android platform does not support synchronous requests. #### TLS Support Transport Layer Security (TLS) is a protocol that ensures privacy between communicating applications and their users on the Internet. When a server and client communicate, TLS ensures that no third party may eavesdrop or tamper with any message. TLS is the successor to the Secure Sockets Layer (SSL). To communicate to servers with the TLS protocol, you need to use the same TLS version between the client and server.
TLS versions by platform
Protocol Android iOS
TLS 1.0 1.0+ 1.0+
TLS 1.1 4.1+ 5.0+
TLS 1.2 4.1+ 5.0+
TLS 1.3 10.0+ 12.2+
In Titanium, if a connection with TLS 1.2 fails, Titanium will re-attempt the connection with TLS 1.1 and TLS 1.0. By default, TLS 1.2 is attempted first. On Android, use the [Titanium.Network.HTTPClient.tlsVersion](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#tlsVersion) property to set the version of the TLS protocol if you know the version the server is running. If you do not know, do not set this property. On iOS, add the `NSExceptionMinimumTLSVersion` key in the `` section of `tiapp.xml` to set a minimum TLS version. See following example: ``` NSAppTransportSecurity NSExceptionDomains www.titaniumsdk.com NSExceptionMinimumTLSVersion [string](https://titaniumsdk.com/docs/sdk/Global.String.md)TLSv1.3 ``` Titanium will not fallback with a lower TLS version if the `tlsVersion` property in android or `NSExceptionMinimumTLSVersion` in iOS, is set. Setting the TLS version saves time from re-attempting connections with lower TLS versions and provides added security by denying attempts to use lower TLS versions. #### Caching Data You can also use the HTTP client API to cache image, response data or related. A convenient way to do so is by setting the [Titanium.Network.HTTPClient.file](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#file) property to a path or target file, which will be populated with the response data in a successful case (e.g. in the `onload` callback). For more complex use cases, make sure to check [To.ImageCache](https://github.com/Topener/To.ImageCache/) which also supports expire-handling and extended cache control. #### Android Platform Implementation Notes On Android, the `HTTPClient` uses its own cookie store which does not share cookies with the system cookie store used by [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md). Developers can manage their cookies for both cookie stores using the methods [Titanium.Network.addHTTPCookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#addHTTPCookie), [Titanium.Network.addSystemCookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#addSystemCookie), [Titanium.Network.getHTTPCookies](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#getHTTPCookies), [Titanium.Network.getHTTPCookiesForDomain](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#getHTTPCookiesForDomain), [Titanium.Network.getSystemCookies](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#getSystemCookies), [Titanium.Network.removeHTTPCookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#removeHTTPCookie), [Titanium.Network.removeHTTPCookiesForDomain](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#removeHTTPCookiesForDomain), [Titanium.Network.removeAllHTTPCookies](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#removeAllHTTPCookies), [Titanium.Network.removeSystemCookie](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#removeSystemCookie), [Titanium.Network.removeAllSystemCookies](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#removeAllSystemCookies). #### Connect to local network in iOS On iOS 14 and later, while connecting to local network a prompt will be shown to request user's permission. Add key `NSLocalNetworkUsageDescription` to the `ios plist` section of the tiapp.xml file to show the message on prompt. If this key is not added default message will be shown in prompt. Example: ``` xml NSLocalNetworkUsageDescription [string](https://titaniumsdk.com/docs/sdk/Global.String.md) Specify the reason for accessing the local network. This appears in the alert dialog when asking the user for permission to access local network. ``` ## Example: Simple GET Request The following code excerpt does a simple GET request and logs the response text. ``` js var url = "http://www.titaniumsdk.com"; var client = Ti.Network.createHTTPClient({ // function called when the response data is available onload : function(e) { Ti.API.info("Received text: " + this.responseText); alert('success'); }, // function called when an error occurs, including a timeout onerror : function(e) { Ti.API.debug(e.error); alert('error'); }, timeout : 5000 // in milliseconds }); // Prepare the connection. client.open("GET", url); // Send the request. client.send(); ``` ## Properties ### allResponseHeaders - Type: String - Platforms: Android - Permission: read-only All of the response headers. Contains a single string, or an empty string if no headers are available. See also: [getResponseHeader](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#getResponseHeader). ### autoEncodeUrl - Type: Boolean - Platforms: Android - Default: `true` Determines whether automatic encoding is enabled for the specified URL. Set to `false` to disable automatic URL-encoding. ### autoRedirect - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `true` Determines whether automatic automatic handling of HTTP redirects is enabled. Set to `false` to disable automatic HTTP redirects handling. ### cache - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 2.0.0 - Default: `false` Determines whether HTTP responses are cached. If `cache` is set to `true`, requests using this HTTP client will cache their responses (respecting headers such as "no-cache", "no-store", and cache expiry). In this case, repeated requests to the same URL may retrieve the initial response rather than triggering a new request. The cache is shared between all instances of `HTTPClient`. Caching should only be enabled for HTTP requests which you expect the result to remain consistent for. If `cache` is `false`, any request on this HTTP client will result in a new HTTP request. This propery must be set before `open` is called. ### connected - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Indicates whether the response was successful. ### connectionType - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Connection type, normally either `GET`, `POST` or `PATCH`. ### domain - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 - Default: `Undefined` Sets the domain parameter for authentication credentials. Set this parameter when authentication against NTLM domains along with the [username](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#username) and [password](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#password) properties. iOS supports NTLM authentication natively. Android can be extended using the [addAuthFactory](Titanium.Network.HTTPClient.addAuthFactory) method. Must be set before calling [open](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#open). ### DONE - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Ready state constant indicating that the request is complete. In this ready state, either the data has been transferred, or an error has occured. See also [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState). ### enableKeepAlive - Type: Boolean - Platforms: iPhone, iPad, macOS - Default: `false` Determines whether the client should attempt to keep a persistent connection. Set to `true` to maintain a persistent connection. ### file - Type: String | Titanium.Filesystem.File - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.4.0 Target local file or file path to receive data. This property can be set anytime prior to calling [send](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#send). The file must be writable such as the application data directory or temp directory. ### HEADERS_RECEIVED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Ready state constant indicating that response headers have been received. See also [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState). ### LOADING - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Ready state constant indicating that response data is being received from the remote server. See also [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState). ### location - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Absolute URL of the request. If the request redirects, this property returns the URL of the redirected request. ### ondatastream - Type: Callback - Platforms: Android, iPhone, iPad, macOS Function to be called at regular intervals as the request data is being received. Must be set before calling `open`. The `progress` property of the event will contain a value from 0.0-1.0 with the progress of the request. If the progress can not be calculated, the value will be [PROGRESS_UNKNOWN](https://titaniumsdk.com/docs/sdk/Titanium.Network.md#PROGRESS_UNKNOWN). ### onerror - Type: Callback - Platforms: Android, iPhone, iPad, macOS Function to be called upon a error response. Must be set before calling `open`. The callback's argument is an object with a single property, `error`, containing the error string. ### onload - Type: Callback - Platforms: Android, iPhone, iPad, macOS Function to be called upon a successful response. Must be set before calling `open`. To access response data and headers, access the `HTTPClient` object itself (accessible as `this` during the callback, or the `source` property of the callback event). ### onreadystatechange - Type: Callback - Platforms: Android, iPhone, iPad, macOS Function to be called for each [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState) change. Must be set before calling `open`. When the callback is invoked, `this.readyState` is set to one of the `Titanium.Network.HTTPClient` ready-state constants, [OPENED](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#OPENED), [HEADERS_RECEIVED](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#HEADERS_RECEIVED), [LOADING](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#LOADING), or [DONE](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#DONE). Due to the asynchronous nature of the Titanium platform, the internal value of [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState) might be different from the state change for which the event was fired. To address this discrepancy, the function is now invoked with a payload object of type [ReadyStatePayload](https://titaniumsdk.com/docs/sdk/ReadyStatePayload.md). This is supported on the iOS and Android platforms. ### onsendstream - Type: Callback - Platforms: Android, iPhone, iPad, macOS Function to be called at regular intervals as the request data is being transmitted. Must be set before calling `open`. The `progress` property of the event will contain a value from 0.0-1.0 with the progress of the upload. ### OPENED - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Ready state constant indicating that the connection has been opened, but the request has not yet been sent. See also [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState). ### password - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 - Default: `Undefined` Sets the password parameter for authentication credentials. Must be set before calling [open](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#open). ### readyState - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only The current ready state of this HTTP request. The ready state describes the current state of the request. The ready state is set to one of the five `Titanium.Network.HTTPClient` ready state constants. A typical HTTP request goes through the states in this order: * [UNSENT](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#UNSENT) * [OPENED](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#OPENED) * [HEADERS_RECEIVED](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#HEADERS_RECEIVED) * [LOADING](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#LOADING) * [DONE](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#DONE) The `onreadystatechange` callback is invoked each time the ready state changes. Accepts: `Titanium.Network.HTTPClient.DONE`, `Titanium.Network.HTTPClient.HEADERS_RECEIVED`, `Titanium.Network.HTTPClient.LOADING`, `Titanium.Network.HTTPClient.OPENED`, `Titanium.Network.HTTPClient.UNSENT` ### responseData - Type: Titanium.Blob - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Response data as a `Blob` object. ### responseDictionary - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Response as JSON object. Set to `null` if the content type returned by the server was not a JSON or if the content could not be parsed. ### responseHeaders - Type: Dictionary - Platforms: iPhone, iPad, macOS - Permission: read-only Returns all the response headers returned with the request. Contains a dictionary of response headers only after the http call has finished. See also: [getResponseHeader](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#getResponseHeader). ### responseText - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Response as text. Set to `null` if an error was received or no data was returned. ### responseXML - Type: Titanium.XML.Document - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Response object as an XML DOM Document object. Set to `null` if the content type returned by the server was not XML or if the content could not be parsed. ### securityManager - Type: SecurityManagerProtocol - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.3.0 The Security Manager for this client. This property **must** be specified during creation. Set this property on the HTTPClient to participate in the authentication and resource management of the connection. See [SecurityManagerProtocol](https://titaniumsdk.com/docs/sdk/SecurityManagerProtocol.md) for further information. ### status - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Response HTTP status code. ### statusText - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Human-readable status message associated with the status code. ### timeout - Type: Number - Platforms: Android, iPhone, iPad, macOS - Default: `On iOS, the default is 15000 (15 seconds). ` Timeout in milliseconds when the connection should be aborted. ### timeoutForResource - Type: Number - Platforms: iPhone, iPad - Since: Titanium SDK 9.2.0 - Default: `The default is `7*24*60*60*1000` milliseconds (7 days). ` The maximum amount of time (in milliseconds) that a resource request should be allowed to take. The resource timeout controls how long (in milliseconds) to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout is reached, whichever comes first. For more detail see [timeoutintervalforresource](https://developer.apple.com/documentation/foundation/nsurlsessionconfiguration/1408153-timeoutintervalforresource?language=objc) from Apple documentation. This property also applies if [Ti.Network.HttpClient.waitsForConnectivity](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#waitsForConnectivity) is set to `true`. ### tlsVersion - Type: Number - Platforms: Android - Since: Titanium SDK 3.6.0 - Default: `undefined, behaves as `Ti.Network.TLS_VERSION_1_2`. ` Sets the TLS version to use for handshakes. If you experience handshake failures, set this value to a lower version using the TLS constants in [Titanium.Network](https://titaniumsdk.com/docs/sdk/Titanium.Network.md). 'undefined', 'null', or unsupported values use the default behavior for that Android versions. Setting this property disables falling back to lower TLS versions. Accepts: `Titanium.Network.TLS_VERSION_1_0`, `Titanium.Network.TLS_VERSION_1_1`, `Titanium.Network.TLS_VERSION_1_2`, `Titanium.Network.TLS_VERSION_1_3` ### UNSENT - Type: Number - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Ready state constant indicating that HTTPClient request has not been opened or sent. See also [readyState](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#readyState). ### username - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 3.0.0 - Default: `Undefined` Sets the username parameter for authentication credentials. Must be set before calling [open](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#open). ### validatesSecureCertificate - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Default: `False when running in the simulator or on device in testing mode, and true if built for release in distribution mode. ` Determines how SSL certification validation is performed on connection. On Android, this property is ignored if the `securityManager` property is used to create a custom SSL context and will handle the given URI. ### waitsForConnectivity - Type: Boolean - Platforms: iPhone, iPad - Since: Titanium SDK 9.2.0 - Default: `false` A Boolean value that indicates whether the session should wait for connectivity to become available, or fail immediately. Causes tasks to wait for network connectivity to become available, rather than immediately failing with an error when it is not. When waiting for connectivity, the [Ti.Network.HttpClient.timeout](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#timeout) property does not apply, but the [Ti.Network.HttpClient.timeoutForResource](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#timeoutForResource) property does. ## Methods ### abort - Platforms: Android, iPhone, iPad, macOS Cancels a pending request. ### clearCookies - Platforms: Android, iPhone, iPad, macOS Clears any cookies stored for the host. Parameters: - `host` (String): The URL of the host/domain to clear cookies for. ### getAllResponseHeaders - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK iPhone 10.0.0, iPad 10.0.0, macOS 10.0.0, Android 0.8 All of the response headers. Contains a single string, or an empty string if no headers are available. See also: [getResponseHeader](https://titaniumsdk.com/docs/sdk/Titanium.Network.HTTPClient.md#getResponseHeader). Intended to match the `XMLHTTPRequest` [getAllResponseHeaders API](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/getAllResponseHeaders). Returns: String ### getResponseHeader - Platforms: Android, iPhone, iPad, macOS Returns the value of the specified response header. Parameters: - `name` (String): Name of the header to retrieve. Returns: String ### open - Platforms: Android, iPhone, iPad, macOS Opens the request and prepares the connection. Parameters: - `method` (String): HTTP method for this request, such as 'GET' or 'POST'. 'PATCH' is available on Android from SDK 4.1.0. - `url` (String): URL for the request. - `async` (Boolean, optional): Determines whether the request should be made asynchronously. Only used on iOS. Default: `true`. ### send - Platforms: Android, iPhone, iPad, macOS Sends the request. For POST requests, use the `data` parameter to send POST data. If you pass a serializable JavaScript object, it is automatically turned into form-encoded POST data. You can also send an arbitrary string or binary data (in the form of a [Titanium.Blob](https://titaniumsdk.com/docs/sdk/Titanium.Blob.md)). To send array data, specify each array element individually as a property of the object. For example, normally, you specify an array in an object as: ``` js var payload = { myArray: [1, 2, 3] }; ``` Instead, for the HTTP client to encode the data correctly, you need to send the data as: ``` js var payload = { "myArray[0]" : 1, "myArray[1]" : 2, "myArray[2]" : 3 }; ``` On iOS, you can specify a synchronous request when you call `open` by passing `false` for the `async` parameter. In the case of a synchronous request, `send` blocks until the request is complete. Parameters: - `data` (Object | String | Titanium.Filesystem.File | Titanium.Blob, optional): Data to send with a POST request. Default: `no data`. ### setRequestHeader - Platforms: Android, iPhone, iPad, macOS Sets the value for the specified request header. Must be called after `open` but before `send`. Parameters: - `name` (String): Name of the header to set. - `value` (String): Value to assign to the header. May be `null` to clear a default header value, such as X-Requested-With. ### setTimeout - Platforms: Android, iPhone, iPad, macOS - DEPRECATED since 10.0.0, removed in 10.0.0. Use the property instead. Sets the request timeout. Parameters: - `timeout` (Number): Timeout in milliseconds. ## Inherited members 7 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.