Chilkat.Http Class Overview
Chilkat.Http provides a broad HTTP/HTTPS client for web requests, REST APIs, file downloads, uploads, authentication, cookies, caching, proxies, TLS configuration, Amazon S3 operations, OCSP checks, timestamp authority requests, and detailed HTTP diagnostics.
What the Class Is Used For
Use Chilkat.Http when an application needs to send HTTP requests, call REST APIs, download files, upload request bodies, manage authentication, handle redirects, persist cookies, stream large responses, work through proxies, or perform common S3-compatible storage operations.
REST and Web Requests
Send GET, POST, PUT, PATCH, DELETE, HEAD, and custom HTTP verbs using strings,
JSON, bytes, files, streams, or request objects.
Downloads and Uploads
Download to files, memory, BinData, or
StringBuilder; upload JSON, binary data, text,
or local files.
Authentication
Supports Basic, Digest, NTLM, Negotiate, OAuth 1.0a, OAuth2 bearer tokens,
HTTP signatures, DPoP, and client-certificate authentication.
S3-Compatible Storage
Create buckets, upload and download objects, list buckets, list objects,
delete objects, and generate pre-signed URLs.
Typical Workflow
- Configure common request settings such as Accept, UserAgent, AllowGzip, request headers, timeouts, redirects, cookies, proxy settings, or TLS requirements.
- Configure authentication if required. For example, use BasicAuth with Login and Password, or set AuthToken for OAuth2 bearer-token authentication.
- Choose the request method family that best matches the request body: HttpJson for JSON, HttpStr or HttpSb for text, HttpBinary or HttpBd for binary data, and HttpFile for file uploads.
- Send the request and inspect the returned HttpResponse, or use quick methods such as QuickGetStr and inspect response properties such as LastStatus and LastResponseHeader.
- For failures, check LastErrorText, ConnectFailReason, LastStatus, LastStatusText, LastHeader, and SessionLogFilename.
- Reuse the same Http object for efficient persistent connections, or call CloseAllConnections when finished.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Global Request Headers | Headers that are automatically included with most requests made by the Http object. | SetRequestHeader, RemoveRequestHeader, ClearHeaders, Accept, UserAgent |
| HttpRequest-Based Requests | Requests where headers, path, query parameters, and body are supplied by a HttpRequest object rather than global header properties. | HttpReq, HttpSReq |
| HttpResponse Object | The object returned by many request methods. It contains the status code, response headers, and response body. | HttpJson, HttpStr, HttpBd, HttpNoBody, HttpReq |
| Quick Methods | Convenience methods for common cases where the response body is returned directly and response details are available through Last* properties. | QuickGetStr, QuickGet, QuickGetBd, QuickGetSb, QuickDeleteStr |
| Persistent Connections | HTTP connections may remain open and be reused for later requests to reduce latency and avoid repeated TLS handshakes. | MaxConnections, CloseAllConnections |
| Streaming Large Responses | Large response bodies can be streamed directly to a file rather than kept in memory. | StreamResponseBodyPath, Download, ResumeDownload |
Choosing a Request Method
| Need | Recommended Method | Request Body | Response Handling |
|---|---|---|---|
| Simple GET returning text | QuickGetStr | None | Returns the response body as a string. Status details are available in LastStatus and related properties. |
| Simple GET returning bytes | QuickGet | None | Returns the response body as a byte array. |
| Download to a file | Download | None | Saves the response body directly to a local file. |
| Resume an interrupted download | ResumeDownload, ResumeDownloadBd | None | Continues from the existing file size or existing BinData size. |
| Send JSON | HttpJson | JsonObject | Returns an HttpResponse. |
| Send text | HttpStr, HttpSb | String or StringBuilder | Specify charset and content type, such as utf-8 and application/json. |
| Send binary data | HttpBinary, HttpBd | Byte array or BinData | Useful for PDF, ZIP, images, or arbitrary binary request bodies. |
| Upload a file as the request body | HttpFile | Local file path | Streams the file from disk using the specified content type. |
| Send a request with no body | HttpNoBody | None | Good for GET, HEAD, DELETE, or custom bodyless requests. |
| Send query parameters separately | HttpParams | None | Uses a JsonObject to supply query parameters. |
| Use a fully configured request object | HttpReq, HttpSReq | HttpRequest | Best when headers, path, query parameters, and body are already modeled in an HttpRequest object. |
Important response behavior:
Several Http* methods return
false for HTTP status codes of
400 or higher, but still populate the
HttpResponse object. A response status code of
0 means no HTTP response was received, usually due to a
communication or connection failure.
Request Headers and Content Negotiation
| Feature | Members | Guidance |
|---|---|---|
| Accept header | Accept | Sets the Accept header for most requests. Defaults to */*. |
| User-Agent header | UserAgent | Some servers reject requests without a User-Agent. Set this to identify your application. |
| Host header | AutoAddHostHeader | Enabled by default. The Host header is required by HTTP/1.1. |
| Compression | AllowGzip | Adds Accept-Encoding: gzip by default. Do not include br, because Chilkat does not accept Brotli responses. |
| Custom headers | SetRequestHeader, GetRequestHeader, HasRequestHeader, RemoveRequestHeader, ClearHeaders | Applies to most requests except HttpReq and HttpSReq, which use headers from the supplied HttpRequest. |
| Long header folding | AllowHeaderFolding | Enabled by default. Disable only for rare servers that cannot handle folded MIME-style headers. |
| Reject unexpected content type | RequiredContentType | Causes responses to be rejected if the response Content-Type does not match the required value. |
Best practice:
Avoid manually setting Authorization or
Content-Length. Use the authentication properties for
Authorization, and let Chilkat calculate Content-Length.
Authentication Options
| Authentication Type | Members | When to Use |
|---|---|---|
| Basic Authentication | BasicAuth, Login, Password, SetSecurePassword | Sends a Base64-encoded username/password in the Authorization header. Use only over HTTPS. |
| Digest Authentication | DigestAuth, Login, Password | Uses a challenge-response mechanism where the password is not sent directly. |
| NTLM | NtlmAuth, Login, Password, LoginDomain | Used for Windows Integrated Authentication scenarios. |
| Negotiate | NegotiateAuth | Windows-only authentication option for Negotiate/Kerberos-style environments. |
| OAuth2 Bearer Token | AuthToken, SetAuthTokenSb | Adds Authorization: Bearer ... to requests. AuthToken can also accept JSON for automatic client-credentials token retrieval. |
| OAuth 1.0a | OAuth1, OAuthConsumerKey, OAuthConsumerSecret, OAuthToken, OAuthTokenSecret, OAuthSigMethod, SetOAuthRsaKey | Automatically builds the OAuth 1.0a Authorization header. RSA-SHA1 and RSA-SHA256 require an RSA private key. |
| HTTP Signature | AuthSignature, SetAuthPrivateKey | Used when APIs require an Authorization Signature header. |
| DPoP | SetDPoPKey, AuthToken | Adds a DPoP proof JWT for each request using an EC private key. |
| Client Certificate / mTLS | SetSslClientCert, SetSslClientCertPem, SetSslClientCertPfx, ReceivedCertReq | Used when the HTTPS server requires a client certificate during the TLS handshake. |
| Secure Credential Resolution | EnableSecrets | Allows selected credential properties to resolve secrets from Windows Credential Manager or Apple Keychain using Chilkat secret specification strings. |
TLS, Certificates, and HTTPS
| Need | Use | Notes |
|---|---|---|
| Require server certificate verification | RequireSslCertVerify | When true, HTTPS connections fail if the certificate is expired or cannot be verified. |
| Require hostname match | RequireHostnameMatch | Requires the SNI hostname to match a Subject Alternative Name in the certificate. |
| Set SNI explicitly | SniHostname | Usually needed only when connecting by IP address but the TLS handshake requires a hostname. |
| Apply custom certificate requirements | SetSslCertRequirement | Can require exact or wildcard matches against SubjectDN, SubjectCN, IssuerDN, IssuerCN, or SAN. |
| Pin server public keys | TlsPinSet | Aborts the TLS handshake if the server certificate’s SPKI fingerprint does not match one of the configured pins. |
| Restrict TLS protocol versions | SslProtocol | Prefer settings such as TLS 1.2 or higher rather than requiring one exact protocol version. |
| Restrict cipher suites | SslAllowedCiphers | Can list exact cipher suites or use keywords such as best-practices. |
| Inspect negotiated TLS version and cipher | TlsVersion, TlsCipherSuite | Useful for diagnostics after a TLS connection succeeds or fails. |
| Fetch a server certificate | GetServerCert | Connects to a domain and port to retrieve the server certificate without downloading content. |
Downloads, Large Responses, and Bandwidth
| Feature | Members | Purpose |
|---|---|---|
| Download to file | Download | Saves the response body directly to a local file. Success requires a 2xx status. |
| Append download to file | DownloadAppend | Appends downloaded content to an existing file, creating it if needed. |
| Download to memory bytes | QuickGet, DownloadBd, QuickGetBd | Use for binary responses that fit comfortably in memory. |
| Download text | QuickGetStr, DownloadSb, QuickGetSb | Use charset-aware methods when converting response bytes to text. |
| Stream response body to file | StreamResponseBodyPath | Streams response bodies from methods returning HttpResponse directly to a file. |
| Resume downloads | ResumeDownload, ResumeDownloadBd | Continues from a partially downloaded file or existing BinData. |
| Limit response size | MaxResponseSize | Protects the application from unexpectedly large responses. |
| Throttle transfers | BandwidthThrottleDown, BandwidthThrottleUp | Limits download or upload bandwidth in bytes per second. |
| Hash a download | DownloadHash | Downloads content and returns an encoded hash such as SHA-256 in hex or Base64. |
Cookies and Redirects
| Capability | Members | How It Works |
|---|---|---|
| Persist cookies | SaveCookies, CookieDir | Cookies are stored in XML files under CookieDir, or in memory when CookieDir = "memory". |
| Send stored cookies | SendCookies | Automatically adds matching cookies to outgoing requests based on domain and path. |
| Inspect or restore cookies | GetCookieXml, SetCookieXml, ClearInMemoryCookies | Useful for persisting cookies in a database or clearing memory-only cookies. |
| Follow redirects | FollowRedirects, WasRedirected, FinalRedirectUrl | Automatically follows common redirect status codes when enabled. |
| Control redirected verb | RedirectVerb | Defaults to GET, matching browser-like behavior. Set to empty to reuse the original HTTP verb. |
| Extract META refresh URL | ExtractMetaRefreshUrl | Convenience method for extracting a redirect URL from an HTML META refresh tag. |
HTTP Cache Support
Chilkat.Http includes browser-like disk caching for HTTP GET responses. It is intended for web-page style caching, not as a general REST API response cache. Only GET responses are cached, and responses containing Set-Cookie headers are not cached.
| Need | Use | Notes |
|---|---|---|
| Add cache storage locations | AddCacheRoot | Call one or more times to define cache root directories. |
| Fetch from cache when possible | FetchFromCache | Uses cached GET responses when available and fresh. |
| Update cache from GET responses | UpdateCache | Automatically stores eligible GET responses. |
| Inspect cache result | LastFromCache | Indicates whether the previous GET was served from cache. |
| Control freshness | FreshnessAlgorithm, DefaultFreshPeriod, LMFactor, MinFreshPeriod, MaxFreshPeriod | Controls how long cached responses are considered fresh when response headers do not provide explicit expiration information. |
| Configure cache directory layout | NumCacheRoots, NumCacheLevels, GetCacheRoot | Multiple cache levels help avoid too many files in one directory. |
| Override cache-control behavior | IgnoreNoCache, IgnoreMustRevalidate | Use carefully; these settings intentionally ignore server caching instructions. |
Amazon S3 and S3-Compatible Storage
The class includes convenience methods for Amazon S3 and S3-compatible services. Configure the AWS credentials and endpoint properties before using the S3_* methods.
| Area | Members | Purpose |
|---|---|---|
| Credentials and endpoint | AwsAccessKey, AwsSecretKey, AwsSessionToken, AwsRegion, AwsEndpoint | Supports regular AWS keys, temporary STS credentials, regional endpoints, and S3-compatible service endpoints. |
| Bucket operations | S3_CreateBucket, S3_DeleteBucket, S3_ListBuckets | Create, delete, and list buckets. |
| List objects | S3_ListBucketObjects | Returns XML listing information for objects in a bucket. |
| Upload objects | S3_UploadFile, S3_UploadBytes, S3_UploadBd, S3_UploadString | Upload from local files, byte arrays, BinData, or text. |
| Download objects | S3_DownloadFile, S3_DownloadBytes, S3_DownloadBd, S3_DownloadString | Download to files, byte arrays, BinData, or text strings. |
| Delete objects | S3_DeleteObject, S3_DeleteObjects | Delete one object or multiple objects in a single request. |
| Object existence | S3_FileExists | Returns 1 if present, 0 if absent, and -1 if the check failed. |
| Pre-signed URLs | S3_GenPresignedUrl | Generates temporary signed URLs for operations such as GET, PUT, POST, or DELETE. |
| S3 sub-resources and metadata | AwsSubResources, SetRequestHeader | Use for S3 sub-resources such as acl or versionId, and for adding x-amz-* headers. |
Endpoint note:
For buckets outside us-east-1, or when using
S3-compatible services such as Wasabi, set AwsEndpoint
and AwsRegion appropriately.
Proxy Support
| Proxy Type | Members | Notes |
|---|---|---|
| HTTP Proxy | ProxyDomain, ProxyPort, ProxyLogin, ProxyPassword, ProxyAuthMethod, ProxyLoginDomain | Supports Basic, Digest, and NTLM proxy authentication. Setting ProxyAuthMethod = "basic" can avoid an initial proxy challenge round trip. |
| Direct TLS to Proxy | ProxyDirectTls | Use when the proxy itself expects the initial connection to be TLS. |
| Internet Explorer Proxy Settings | UseIEProxy | Uses the proxy address and port from Internet Explorer settings, but not proxy exceptions. |
| SOCKS Proxy | SocksVersion, SocksHostname, SocksPort, SocksUsername, SocksPassword | Supports SOCKS4 and SOCKS5. Use SocksVersion = 4 or 5 to enable. |
Specialized Security and Utility Methods
| Capability | Members | Purpose |
|---|---|---|
| Google service account OAuth token | G_SvcOauthAccessToken, G_SvcOauthAccessToken2 | Obtains OAuth2 access tokens for Google service-account flows. |
| OCSP certificate status | CreateOcspRequest, ParseOcspReply, OcspCheck | Builds, sends, parses, or directly checks OCSP certificate revocation status. |
| RFC 3161 timestamping | CreateTimestampRequest, VerifyTimestampReply | Creates timestamp authority requests and verifies timestamp replies. |
| URL utilities | UrlEncode, UrlDecode, GetDomain, GetUrlPath | Encodes/decodes URL text and extracts URL components. |
| URL variable substitution | SetUrlVar, ClearUrlVars | Allows URLs to contain placeholders such as {$id}. |
| DNS cache management | DnsCacheClear | Clears Chilkat’s shared in-memory DNS cache. |
| HTTP date generation | GenTimeStamp | Returns the current UTC date/time in HTTP date format. |
| Render a GET request without sending | RenderGet | Useful for debugging the exact GET request that would be sent. |
Diagnostics and Troubleshooting
HTTP failures can occur at several layers: DNS, TCP connection, proxy authentication, TLS handshake, request transmission, server response, redirect handling, or application-level API errors. Chilkat exposes diagnostics for each layer.
| Diagnostic Need | Use |
|---|---|
| Detailed text for the last operation | LastErrorText |
| Connection failure category | ConnectFailReason |
| Most recent HTTP status code and text | LastStatus, LastStatusText |
| Last request header sent | LastHeader |
| Last response header received | LastResponseHeader |
| Last content type | LastContentType |
| Last-Modified header | LastModDate |
| Keep text response body for methods without HttpResponse output | KeepResponseBody, LastResponseBody |
| Log exact HTTP requests and responses to a file | SessionLogFilename |
| Inspect extra structured data after selected calls | GetLastJsonData |
| Check redirect behavior | WasRedirected, FinalRedirectUrl |
| Inspect TLS details | TlsVersion, TlsCipherSuite |
Status-code reminder:
HTTP 2xx generally means success,
3xx means redirection,
4xx means a client-side or request problem,
and 5xx means a server-side failure.
Best Practices
| Recommendation | Reason |
|---|---|
| Use the body-specific Http* method that matches your request. | HttpJson, HttpStr, HttpBd, and HttpFile make body encoding and content type clearer. |
| Use HttpResponse methods for REST APIs. | They provide direct access to status code, headers, and response body, including error responses. |
| Set UserAgent for public web servers. | Some servers reject requests that omit a User-Agent header. |
| Use AuthToken for OAuth2 bearer tokens instead of manually setting Authorization. | It keeps authentication behavior centralized and avoids malformed headers. |
| Use StreamResponseBodyPath or Download for large responses. | Avoids loading large response bodies entirely into memory. |
| Use MaxResponseSize for untrusted endpoints. | Protects the application from unexpectedly large responses. |
| Use RequireSslCertVerify and RequireHostnameMatch for stricter HTTPS validation. | Strengthens TLS server authentication when production security requires it. |
| Use EnableSecrets for credentials. | Allows credentials to be resolved from Windows Credential Manager or Apple Keychain instead of being embedded directly in source code. |
| Use SessionLogFilename for difficult HTTP or proxy cases. | The exact HTTP request/response transcript is often the fastest way to diagnose authentication, redirect, header, or API formatting problems. |
Summary
Chilkat.Http is a comprehensive HTTP/HTTPS client class for applications that need to call APIs, download and upload data, authenticate with modern and legacy schemes, manage cookies and redirects, stream large responses, work through proxies, use TLS client certificates, perform S3-compatible storage operations, and diagnose HTTP communication in detail.
For lower-level request construction, use HttpRequest with HttpReq or HttpSReq. For simple GET and DELETE convenience calls, use the Quick* methods.