Configuring Your Application at Design Time

Creating an HTTP Client

To create an HTTP client that you can use to send HTTP request, drag a TNetHTTPClient from the Tool Palette onto a form or data module of your application. The TNetHTTPClient does not require any initial configuration.

Creating and Configuring HTTP Requests

You also need to drop one or more TNetHTTPRequest components onto your form or data module.

After you drop your new HTTP request component, double-click its Client property on the Object Inspector so that its value is the HTTP client component that you previously dropped.

You can use any number of request components that you like. However, if you need to send several different HTTP requests, a better approach might be to use a single HTTP request component and reconfigure that component at run time to send each request.

Sending a Request and Handling its Response

Sending an HTTP Request

The HTTP request method determines the action that you want the server to perform on the resource located at the specified URL, such as sending you the data of the resource or updating the resource with data that you include in your request.

How you send an HTTP request using a TNetHTTPRequest component depends on the HTTP request method that you want to use.

Sending an HTTP Request Using the MERGE, PATCH, or PUT HTTP Request Methods

To send an HTTP request using any of these HTTP request methods, call its matching function as shown in the table below. In your call, specify the URL of the target resource as your first argument and an instance of TStream as your second argument.

* Some HTTP proxies do not support the latest standard HTTP request methods (such as PATCH) or non-standard HTTP request methods (such as MERGE). In these cases, you can proxy HTTP request methods through another HTTP request method. To do this, the request includes headers that specify the intended HTTP request method.

Sending an HTTP Request Using the POST HTTP Request Method

To send an HTTP request using the POST HTTP request method, call Post. In your call, you must specify the URL of the target resource as your first argument. The other arguments depend on how you want to provide the input data of your request:

To send the content of a local file, specify the local path to that file as the second argument of your call.

To send the content of a stream, provide your instance of TStream as the second argument of your call.

To send the content of a string list, provide your instance of TStrings as the second argument of your call, and if your strings are not encoded in UTF-8, provide an instance of TEncoding as the fourth argument. For example:

Handling an HTTP Response

When the target server sends a response to your request, the OnRequestCompleted event of your HTTP request component occurs. Define an event handler for this event to read the data from the server response. If there is an error during your request, the OnRequestError event of your HTTP request component occurs instead.

Managing Cookies

The AllowCookies property of the HTTP client component allows you to specify whether you want to accept the cookies that the server sends in the response.
If AllowCookies is True, the HTTP client saves the received cookies in his CookieManager.

Handling Redirects

Use the HandleRedirects property to control how the HTTP client component handles redirects. The default value is True, which means that the HTTP client component automatically follows redirects.

Use the MaxRedirects property of the HTTP client component to specify a maximum number of redirects that you allow the component to follow. If the HTTP client component reaches the specified number of maximum redirects, it raises an exception of type ENetHTTPRequestException.

Handling the Download of the Response Data

As your HTTP client downloads the response to your request, the OnReceiveData event of your HTTP request object keeps occurring. Provide an event handler for OnReceiveData to keep track of the progress of the download of the response data. Your event handler receives the following parameters:

Sender, which is your HTTP request object.

AContentLength, which is the expected length of the response data in number of bytes.

AReadCount, which is the number of bytes of the response data that the HTTP client has downloaded so far.

Abort, which is a Boolean parameter that allows you to cancel the download.

When the download finishes, OnReceiveData occurs for the last time, and the values of AContentLength and AReadCount are the same. OnRequestCompleted occurs soon afterwards.

Tracking the Progress of the Download of the Response Data

To track the progress of the downloaded data, use the values of AContentLength and AReadCount in the OnReceiveData event handler.
This is an example that calculates the percentage of the downloaded data:

When you execute a request, the THTTPClient.Execute method of the HTTP framework combines the custom headers from the HTTP client component and the corresponding HTTP request component and adds those headers to the final request.

Handling Authentication and Certificates

Handling HTTP Basic Access Authentication

When you send an HTTP request to a server that requires HTTP basic access authentication, the OnAuthEvent of your HTTP client object occurs. To submit your access credentials, provide an event handler for this event and, if the value of the second parameter that the event handler receives (AnAuthTarget) is TAuthTargetType.Server, fill the AUserName and APassword variables with your username and password for HTTP access. For example:

Alternatively, you can specify the credential for proxy authentication in the OnAuthEvent event handler. See the Handling HTTP Basic Access Authentication section, and check that the value of AnAuthTarget is TAuthTargetType.Proxy instead of TAuthTargetType.Server.

Handling System Proxy Settings With an HTTP Client

The following table explains how the HTTP Client handles the system proxy settings on different platforms:

Platform

Behavior

Windows

The HTTP Client uses the system proxy settings. You can bypass the system proxy settings and you can also provide alternative proxy settings for the HTTP Client.

To bypass the system proxy settings, create proxy settings for the HTTP Client and specify http://direct as the URL.

MAC OS X

The HTTP Client always uses the system proxy settings. Even if you provide alternative proxy settings for the HTTP Client, the HTTP Client uses the system proxy settings.

iOS

The HTTP Client always uses the system proxy settings. Even if you provide alternative proxy settings for the HTTP Client, the HTTP Client uses the system proxy settings.

Android

The HTTP Client uses the system proxy settings. You cannot bypass those settings, but you can provide alternative proxy settings for the HTTP Client.

Note: If the system does not specify any proxy settings (the connection is direct), that is also considered a "setting". For example, on iOS or MAC OS X with no system proxy settings, you cannot provide proxy settings for the HTTP Client. The settings that you provide are ignored because the system settings (the "no proxy" setting) are used.

Managing the Storage of User Credentials

This example demonstrates how to use TNetHTTPClient.CredentialsStorage to save a credential and then use that credential to authenticate when connecting to an HTTP server that requires basic authentication:

Create a credential and add that credential to your credential storage:

Handling Server-side Certificates

If the server provides an SSL certificate, but this certificate is invalid, the OnValidateServerCertificate event occurs. Provide an event handler for OnValidateServerCertificate so that you can check the server certificate (Certificate) and determine whether or not you accept the server certificate. If you accept the server certificate, change the value of the Accept parameter to True.

Handling Client-side Certificates

If the server requires a client certificate, the OnNeedClientCertificate event occurs. Provide an event handler for OnNeedClientCertificate so that you can check your list of client certificates (ACertificateList), and determine which certificate you want to send to the server. To send a given certificate from the list, change the value of AnIndex to the index of the target certificate in ACertificateList.

Note: If the HTTP method of the first request to a server that requires a client-side certificate is not either HEAD or GET (e.g. it is POST), the status code of the server response is 413. Always send a HEAD or GET request first. Using a HEAD request is usually a better choice, since less data is transferred.

Making Requests Asynchronous

Requests are synchronous by default. During a request, the execution of your application stops when you start your request, and only resumes when you obtain a response from the server or the request times out.

If you want to make your requests asynchronous, so that requests do not stop the execution of your application, you must enable the Asynchronous property of the client component or the Asynchronous property of the request component, depending on which component you use to perform your request.