Rest Pascal Reference Documentation
Rest
Current Version: 11.5.0
Chilkat.Rest
Build REST requests with explicit paths, headers, query parameters,
request bodies, content types, and HTTP methods.
Connect once and send multiple requests over the same underlying
connection when appropriate.
Work with bearer tokens, OAuth2, AWS-style signing, Azure and Google
auth helpers, and other service-specific authentication patterns.
Send JSON, XML, text, binary data, form parameters, multipart requests,
streams, and file-based request bodies.
Read response bodies as strings, bytes, streams, JSON, XML, or
Use detailed error text, raw request generation, response headers,
connection state, and verbose diagnostics to troubleshoot API behavior.
For an extended overview, see
Rest Class Overview.
Build, send, authenticate, stream, and inspect REST API requests with precise control.
Chilkat.Rest is a flexible REST client class for applications
that need detailed control over request construction, connection reuse,
authentication, headers, query parameters, multipart bodies, streaming
uploads and downloads, response parsing, and low-level diagnostics. It is
especially useful for APIs where the application must carefully manage
provider-specific signing, request paths, body formats, and server responses.
Precise request construction
Connection reuse
Authentication support
Request bodies and multipart
Response handling
StringBuilder content, and inspect status codes and headers.
Diagnostics and debugging
Chilkat.Rest when you want fine-grained control over the
connection and request construction. For higher-level HTTP convenience
methods that accept full URLs directly, use Chilkat.Http. For
advanced socket routing, create the connection with Chilkat.Socket
and pass it to UseConnection.
Rest object
until they are replaced or cleared. When reusing an object for unrelated requests,
call the applicable Clear* methods rather than assuming request state
is automatically reset.
SendReq* call, call ReadResponseHeader and then read
the response body exactly once when a body is present. Fully consume the body before
sending another request on the same connection. A HEAD response has no
body; a 204 No Content response is represented by an empty body.
Rest class exposes redirect and response-header information but does
not automatically follow redirects or maintain a cookie jar. Applications should
process Location and Set-Cookie values explicitly when needed.
Create / Free
uses
Chilkat.Rest;
var
obj: TRest;
begin
obj := TRest.Create;
try
if not obj.IsValid then
raise Exception.Create('Failed to create a TRest instance.');
// ... use obj ...
finally
obj.Free;
end;
end;
Allocates the underlying CkRest object and returns a new TRest instance. Simply adding Chilkat.Rest to the unit's uses clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check obj.IsValid after calling Create; it is False if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed).
Every TRest created by calling Create should eventually be released by calling .Free (inherited from TObject). The destructor automatically disposes the underlying CkRest handle. A native (unmanaged) memory leak occurs if the object is never freed.
Properties
AllowHeaderFolding
Controls whether long request-header fields may be folded onto continuation lines. The default is False. When set to False, each request header is emitted on a single physical line.
False when the service requires unfolded header lines, as is common for canonicalized request signatures.AllowHeaderQB
Controls whether non-ASCII request-header values may be converted to RFC 2047 encoded-word form using Q or Base64 encoding. The default is True.
Encoded words have forms such as =?utf-8?Q?...?= and =?utf-8?B?...?=. When this property is False, Chilkat does not apply this conversion.
Authorization
Gets or sets the value sent in the HTTP Authorization request header. Supply only the field value, such as Bearer eyJ..., not the text Authorization:.
SetAuth* method. A configured authentication provider may generate or replace the Authorization header when the request is sent.SetAuth* provider is active, its generated Authorization header takes precedence over this property and over a manually added Authorization header. ClearAuth clears both the provider and this value; clearing top-level headers also clears this property.ConnectFailReason
After Connect fails, returns a code identifying the connection stage or TLS handshake stage that failed.
| Code | Meaning |
|---|---|
0 | Success |
1 | Empty hostname |
2 | DNS lookup failed |
3 | DNS timeout |
4 | Aborted by the application |
5 | Internal failure |
6 | Connection timed out |
7 | Connection rejected or otherwise failed |
99 | Chilkat is not unlocked or the trial expired |
TLS-related codes:
| Code | Meaning |
|---|---|
100 | TLS internal error |
101 | Failed to send ClientHello |
102 | Unexpected handshake message |
103 | Failed to read ServerHello |
104 | No server certificate |
105 | Unexpected TLS protocol version |
106 | Server certificate verification failed |
107 | Unacceptable TLS protocol version |
109 | Failed to read handshake messages |
110 | Failed to send the client-certificate handshake message |
111 | Failed to send ClientKeyExchange |
112 | Client certificate private key is inaccessible |
113 | Failed to send CertificateVerify |
114 | Failed to send ChangeCipherSpec |
115 | Failed to send Finished |
116 | The server Finished message is invalid |
LastErrorText for the full failure context.Connect resets this property to 0. HTTP response properties are separate and are not cleared by a later failed connection attempt.ConnectTimeoutMs
Gets or sets the maximum number of milliseconds to wait for the remote server to accept the TCP connection. This timeout covers connection establishment, not the later sending or receiving of HTTP data.
IdleTimeoutMs to control how long an established operation may remain without send or receive progress.The default is 30000 milliseconds.
DebugLogFilePath
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
DebugMode
When True, calls to the Send* and FullRequest* methods compose the complete request but do not transmit it. Retrieve the generated request with GetLastDebugRequest. The default is False.
In debug mode, a composed full-request call reports a synthetic successful result with ResponseStatusCode equal to 201, ResponseStatusText equal to OK, and no actual response header or response body.
EnableSecrets
Controls automatic resolution of credentials from operating-system secure storage. The default is False.
When set to True, supported credential inputs may contain a secret specification beginning with !! instead of a literal secret. Chilkat resolves the specification from Windows Credential Manager on Windows or Apple Keychain on macOS.
The specification format is:
!![appName|]service[|domain]|username
For this class, secret specifications apply to the username and password supplied to SetAuthBasic.
HeartbeatMs
Controls the interval, in milliseconds, between AbortCheck event callbacks during supported long-running operations. The default is 0, which disables periodic AbortCheck callbacks.
Host
Gets or sets the value of the HTTP Host request header.
Connect or UseConnection. Set this property explicitly only when the request must present a different virtual-host value.An explicitly assigned value overrides the generated HTTP Host field, but it does not change the TCP/TLS destination established by Connect or UseConnection.
IdleTimeoutMs
Gets or sets the maximum number of milliseconds to wait when a send or receive operation has stopped making progress. The default is 30000 milliseconds.
A value of 0 disables the inactivity timeout.
LastErrorHtml
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
Indicates the success or failure of the most recent method call: True means success, False means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
LastRedirectUrl
Returns the redirect target from the most recently received response. The value comes from the response Location header. If the most recent response was not a redirect or did not contain a Location header, this property is empty.
Rest does not automatically follow the redirect; send a new request explicitly, reconnecting first if the target host changes.LastRequestHeader
Returns the HTTP header fields from the most recently composed request, excluding the request line. The request line is available separately in LastRequestStartLine.
A failed Connect does not clear this value. It continues to describe the last request that was composed and sent.
LastRequestStartLine
Returns the request line from the most recently composed request. It contains the HTTP method, request target, and HTTP version, for example:
GET /v1/items?limit=10 HTTP/1.1
A failed Connect does not clear this value. It continues to describe the last request that was composed and sent.
NumResponseHeaders
Returns the number of response header field occurrences. Enumerate them with zero-based indexes using ResponseHdrName and ResponseHdrValue.
A failed Connect does not reset this count; it remains the count for the last received HTTP response.
PartSelector
Selects the multipart entity or part targeted by multipart-building operations such as AddHeader, RemoveHeader, and the SetMultipartBody* methods.
| Value | Selected target |
|---|---|
| The top-level request entity |
0 | The top-level request entity |
1 | The first multipart subpart |
2 | The second multipart subpart |
1.2 | The second child within the first subpart |
The value 0, like the empty string, selects the top-level request entity. A nonnumeric selector is invalid. A body assignment can create a higher-numbered part even when lower-numbered parts do not yet exist.
PercentDoneOnSend
Applies to the full-request methods that both upload a request and download a response. It selects which direction is represented by percent-complete events.
False(default): progress refers to receiving the response body.True: progress refers to sending the request body.
ResponseHeader
Returns the HTTP response header fields from the most recently received response, excluding the status line.
ResponseStatusCode and ResponseStatusText.Repeated fields remain separate and in received order. The field-name casing is preserved. A failed Connect does not clear this value; it continues to describe the last received HTTP response.
ResponseStatusCode
Returns the numeric HTTP status code from the most recently received response, such as 200, 404, or 503.
400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Connect does not clear this property. It continues to report the status of the last HTTP response that was actually received.ResponseStatusText
Returns the reason phrase associated with the most recently received HTTP status code, such as OK or Not Found.
Connect does not clear this property; it remains associated with the last received HTTP response.StreamNonChunked
Controls whether streaming uploads use a Content-Length header instead of HTTP/1.1 chunked transfer encoding when the total body size is known. The default is True.
When True and the stream length can be determined—for example, a file stream—Chilkat sends a non-chunked request. When False, Chilkat uses Transfer-Encoding: chunked. If the stream length is unknown, chunked transfer may still be required.
UncommonOptions
Provides opt-in compatibility settings for uncommon requirements. The default is the empty string. Supply one or more comma-separated keywords:
| Keyword | Effect |
|---|---|
AllowDuplicateQueryParams | Allows AddQueryParam to append another parameter having the same name instead of replacing the existing one. |
AllowInsecureBasicAuth | Allows Basic authentication over a non-TLS remote connection. By default, Basic authentication is allowed only over TLS, an SSH tunnel, or localhost. |
DisableTls13 | Disables TLS 1.3 so negotiation is limited to TLS 1.2 or earlier supported versions. |
ProtectFromVpn | On Android, attempts to bypass an installed or active VPN for this connection. |
VerboseLogging
If set to True, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is False. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
Methods
AddHeader
const value: string): Boolean;
Adds an HTTP request header using name as the field name and value as the field value. If a request header with the same name is already present for the selected part, its value is replaced.
name—for example, Content-Type—and not the trailing colon. For multipart requests, PartSelector determines whether the header is added to the top-level request or to a MIME part.Request headers persist across requests until removed or cleared. Adding the same header again replaces its current value.
PartSelector. Use an empty selector or 0 for top-level request headers; select a part before adding that part's headers.Returns True for success, False for failure.
AddMwsSignature
const uriPath: string;
const domain: string;
const mwsSecretKey: string): Boolean;
Computes the Amazon Marketplace Web Service (MWS) request signature using the secret key in mwsSecretKey and adds or replaces the Signature query parameter. Call this after all other MWS request parameters have been added.
httpVerb is the HTTP method, uriPath is the MWS resource path, and domain is the request domain. httpVerb and uriPath should match the values used by the request-sending method. The method also adds or replaces the Timestamp parameter using the current system time.
SetAuthAws.Returns True for success, False for failure.
AddPathParam
const value: string): Boolean;
Adds or replaces a path-substitution parameter. Before a request is sent, occurrences of name in the supplied request path are replaced by value.
For example, setting name to fileId and value to abc123 transforms /drive/v3/files/fileId into /drive/v3/files/abc123.
name; braces are not required unless they are part of the placeholder text you choose.Matching is case-sensitive and literal. Every occurrence of name is replaced, substitutions are applied in the order they were added, and replacement applies to the entire uriPath string, including any query portion.
/, ?, and # remain delimiters, and existing percent escapes are preserved. Percent-encode reserved characters before calling this method when they are intended to be data.Path substitutions persist across requests until replaced or removed with ClearAllPathParams.
Returns True for success, False for failure.
AddQueryParam
const value: string): Boolean;
Adds or replaces a query-string parameter using name as the parameter name and value as its value. The stored query parameters are incorporated into the request target when a request is sent.
tag=red&tag=blue, include AllowDuplicateQueryParams in UncommonOptions.name and value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in UncommonOptions.
Returns True for success, False for failure.
AddQueryParams
Adds multiple query parameters from the query-string text in queryString. Use the form field1=value1&field2=value2&field3=value3.
queryString must already be percent-encoded as required for a URL query string. Do not include a leading ?. For individual name/value pairs, AddQueryParam is usually clearer.The input is parsed as an already URL-encoded query string and then normalized when the request is composed. A plus sign is interpreted as a space and is emitted as %20; encoded delimiters such as %26 remain data; an item without an equals sign is treated as a parameter with an empty value.
Parameters added by this method persist across ordinary requests. When ARG2 of a request method already contains a query string, those inline parameters appear first, followed by the parameters stored in the Rest object.
Returns True for success, False for failure.
AddQueryParamSb
function AddQueryParamSb(const name: string;
value: TChilkatBase): Boolean;
Adds or replaces a query-string parameter named by name. The parameter value is read from the StringBuilder in value.
AllowDuplicateQueryParams in UncommonOptions to retain repeated names.name and the text in value are unencoded text. Chilkat percent-encodes the parameter name and value when composing the request target. For example, a space becomes %20, a literal plus sign becomes %2B, and a literal percent sign becomes %25. Existing percent escapes supplied to this method are therefore encoded again. Parameters persist across ordinary requests until removed or cleared.Parameter names are case-sensitive. Adding the same exact name again replaces the existing value unless AllowDuplicateQueryParams is enabled in UncommonOptions.
Returns True for success, False for failure.
ClearAllHeaders
Removes all HTTP request headers previously added to this object.
The method clears headers only from the entity selected by PartSelector. Clearing top-level headers also clears the Authorization property. Automatically generated fields such as Host and Content-Length may be added again when the next request is composed.
Returns True for success, False for failure.
ClearAllParts
Removes all multipart subparts from the request under construction. This is useful when reusing the same REST object after sending a multipart request.
This also resets PartSelector to the empty string and releases the configured multipart bodies and part streams.
Returns True for success, False for failure.
ClearAllPathParams
Removes all path-substitution parameters previously added with AddPathParam.
After clearing, placeholder text in later request paths is sent unchanged.
Returns True for success, False for failure.
ClearAllQueryParams
Removes all query parameters previously added to this object.
This clears the stored query/form parameter collection. It does not remove a query string written directly in the uriPath argument of a request method.
Returns True for success, False for failure.
ClearAuth
Clears authentication providers and credentials previously configured through this class's SetAuth* methods.
This removes the active authentication provider and clears the manually configured Authorization value.
Returns True for success, False for failure.
ClearResponseBodyStream
Clears the response-stream destination previously configured by SetResponseBodyStream. Subsequent full-request methods return or store the response body normally instead of streaming it to that destination.
Clearing the destination does not alter the Stream object itself.
Connect
port: Integer;
tls: Boolean;
autoReconnect: Boolean): Boolean;
Establishes the initial TCP connection to the REST server. hostname is a DNS hostname or an IPv4/IPv6 address, port is the server port, and tls specifies whether the connection uses TLS. Common combinations are port 80 with tls set to False, and port 443 with tls set to True.
If autoReconnect is True, subsequent requests may automatically reconnect when the existing connection is no longer usable. If autoReconnect is False, a lost connection causes the request to fail until the application explicitly reconnects.
hostname is not a URL. For https://api.example.com/v1/items, pass api.example.com. The request path is supplied separately to the request method.Connect is intended for a direct connection. For HTTP or SOCKS proxies, SSH tunneling, client certificates, custom socket routing, or other advanced connection setup, establish a connected Socket and pass it to UseConnection.autoReconnect is True, Chilkat can establish a new connection before a later request after the previous connection has closed. This option should not be interpreted as a promise to replay a request that failed after transmission began.ConnectFailReason to 0. A failed Connect does not clear the HTTP response and last-request properties from an earlier completed exchange; those properties continue to describe the last HTTP request/response, not the failed connection attempt.Returns True for success, False for failure.
ConnectAsync (1)
function ConnectAsync(const hostname: string;
port: Integer;
tls: Boolean;
autoReconnect: Boolean): TChilkatBase;
Creates an asynchronous task to call the Connect method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
Disconnect
Closes the current HTTP connection, if one is open. maxWaitMs is the maximum number of milliseconds to wait while attempting a clean shutdown.
UseConnection, calling Disconnect also disconnects that Socket. If automatic reconnection was enabled, a later request may reconnect it.Returns True for success, False for failure.
DisconnectAsync (1)
function DisconnectAsync(maxWaitMs: Integer): TChilkatBase;
Creates an asynchronous task to call the Disconnect method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestBd
// responseBody is a TStringBuilder object.
function FullRequestBd(const httpVerb: string;
const uriPath: string;
binData: TChilkatBase;
responseBody: TChilkatBase): Boolean;
Sends a complete request whose binary body is read from the BinData in binData. The text response body replaces the existing contents of the StringBuilder in responseBody.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.responseBody is cleared and replaced with the textual response body.
Returns True for success, False for failure.
FullRequestBdAsync (1)
// responseBody is a TStringBuilder object.
// Return value is a TTask object.
function FullRequestBdAsync(const httpVerb: string;
const uriPath: string;
binData: TChilkatBase;
responseBody: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the FullRequestBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestFormUrlEncoded
const uriPath: string): string;
Sends a complete application/x-www-form-urlencoded request. The form body is built from the parameters previously added with AddQueryParam or AddQueryParams. The request Content-Type is set to application/x-www-form-urlencoded. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqFormUrlEncoded, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Parameters written directly in uriPath remain in the URL query string. Parameters stored through AddQueryParam, AddQueryParamSb, or AddQueryParams are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.
Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.Returns True for success, False for failure.
FullRequestFormUrlEncodedAsync (1)
function FullRequestFormUrlEncodedAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the FullRequestFormUrlEncoded method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestMultipart
const uriPath: string): string;
Sends a complete multipart request using the parts and part headers configured through PartSelector, AddHeader, and the multipart-body methods. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqMultipart, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.multipart/form-data.The request fails if no multipart subparts are configured.
Returns True for success, False for failure.
FullRequestMultipartAsync (1)
function FullRequestMultipartAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the FullRequestMultipart method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBody
const uriPath: string): string;
Sends a complete request with no request body. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqNoBody, ReadResponseHeader, and ReadRespBodyString in sequence.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Returns True for success, False for failure.
FullRequestNoBodyAsync (1)
function FullRequestNoBodyAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the FullRequestNoBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBodyBd
function FullRequestNoBodyBd(const httpVerb: string;
const uriPath: string;
binData: TChilkatBase): Boolean;
Sends a complete request without a request body and stores the binary response body in the BinData in binData, replacing its previous contents.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.binData is cleared and replaced with the binary response body.
Returns True for success, False for failure.
FullRequestNoBodyBdAsync (1)
// Return value is a TTask object.
function FullRequestNoBodyBdAsync(const httpVerb: string;
const uriPath: string;
binData: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the FullRequestNoBodyBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestNoBodySb
function FullRequestNoBodySb(const httpVerb: string;
const uriPath: string;
sb: TChilkatBase): Boolean;
Sends a complete request without a request body and stores the text response body in the StringBuilder in sb, replacing its previous contents.
This is the StringBuilder form of FullRequestNoBody.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.sb is cleared and replaced with the textual response body.
Returns True for success, False for failure.
FullRequestNoBodySbAsync (1)
// Return value is a TTask object.
function FullRequestNoBodySbAsync(const httpVerb: string;
const uriPath: string;
sb: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the FullRequestNoBodySb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestSb
// responseBody is a TStringBuilder object.
function FullRequestSb(const httpVerb: string;
const uriPath: string;
requestBody: TChilkatBase;
responseBody: TChilkatBase): Boolean;
Sends a complete request whose text body is read from the StringBuilder in requestBody. The text response body replaces the existing contents of the StringBuilder in responseBody.
This is the StringBuilder form of FullRequestString.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.responseBody is cleared and replaced with the response body.
Returns True for success, False for failure.
FullRequestSbAsync (1)
// responseBody is a TStringBuilder object.
// Return value is a TTask object.
function FullRequestSbAsync(const httpVerb: string;
const uriPath: string;
requestBody: TChilkatBase;
responseBody: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the FullRequestSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestStream
function FullRequestStream(const httpVerb: string;
const uriPath: string;
stream: TChilkatBase): string;
Sends a complete request whose body is read from the Stream in stream. Streaming is appropriate for large uploads because the entire request body need not be held in memory. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqStreamBody, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Returns True for success, False for failure.
FullRequestStreamAsync (1)
// Return value is a TTask object.
function FullRequestStreamAsync(const httpVerb: string;
const uriPath: string;
stream: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the FullRequestStream method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
FullRequestString
const uriPath: string;
const bodyText: string): string;
Sends a complete request whose text body is supplied in bodyText, such as JSON, XML, or plain text. The response body is read as text and returned.
This convenience method performs the equivalent of SendReqStringBody, ReadResponseHeader, and ReadRespBodyString in sequence.
For full-request methods, PercentDoneOnSend selects whether percent-complete events refer to sending the request body or receiving the response body.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.400 or 404 is still a completed HTTP exchange. Inspect ResponseStatusCode and the response body to determine the API-level result.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
FullRequestStringAsync (1)
function FullRequestStringAsync(const httpVerb: string;
const uriPath: string;
const bodyText: string): TChilkatBase;
Creates an asynchronous task to call the FullRequestString method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
GetLastDebugRequest
function GetLastDebugRequest(bd: TChilkatBase): Boolean;
Copies the fully composed HTTP request generated while DebugMode was True into the BinData in bd. The captured data includes the request line, headers, and body that would have been sent.
bd is cleared and replaced. The captured bytes are the complete composed HTTP/1.1 request, including chunk framing when a streaming request uses Transfer-Encoding: chunked.
Returns True for success, False for failure.
GetLastJsonData
procedure GetLastJsonData(json: TChilkatBase);
Copies operation-specific diagnostic or result information from the most recently completed method into the JsonObject in json. Many methods do not produce additional JSON details, in which case the object is empty.
LoadTaskCaller
function LoadTaskCaller(task: TChilkatBase): Boolean;
Loads into this object the caller associated with the Task in task. task must be a task returned by an asynchronous method of this class.
Returns True for success, False for failure.
topReadRespBd
function ReadRespBd(responseBody: TChilkatBase): Boolean;
Reads the response body as raw bytes into the BinData in responseBody, replacing its previous contents. Call this after ReadResponseHeader.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespBdAsync (1)
// Return value is a TTask object.
function ReadRespBdAsync(responseBody: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the ReadRespBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespBodyStream
function ReadRespBodyStream(stream: TChilkatBase;
autoSetStreamCharset: Boolean): Boolean;
Reads the response body into the Stream supplied in stream. Call this after ReadResponseHeader.
If autoSetStreamCharset is True and the response is textual, the stream's StringCharset is set from the charset parameter in the response Content-Type header when one is present. autoSetStreamCharset has no effect for binary responses.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespBodyStreamAsync (1)
// Return value is a TTask object.
function ReadRespBodyStreamAsync(stream: TChilkatBase;
autoSetStreamCharset: Boolean): TChilkatBase;
Creates an asynchronous task to call the ReadRespBodyStream method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespBodyString
Reads the response body as text and returns it. Call this only after ReadResponseHeader has returned the response status code.
ReadRespBd or ReadRespBodyStream for binary or very large content.HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespBodyStringAsync (1)
function ReadRespBodyStringAsync: TChilkatBase;
Creates an asynchronous task to call the ReadRespBodyString method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespChunkBd
function ReadRespChunkBd(minSize: Integer;
bd: TChilkatBase): Integer;
After ReadResponseHeader has been called, reads the next chunk of the response body and appends the received bytes to the BinData in bd. The call waits until at least minSize bytes are available, unless the response ends first. The final chunk may contain fewer than minSize bytes, including zero bytes.
| Return value | Meaning |
|---|---|
-1 | The read failed; inspect LastErrorText. |
0 | The remaining response bytes were returned and the response body is complete. |
1 | A chunk was returned and more response bytes remain. |
Returns True for success, False for failure.
ReadRespChunkBdAsync (1)
// Return value is a TTask object.
function ReadRespChunkBdAsync(minSize: Integer;
bd: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the ReadRespChunkBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadResponseHeader
Reads the HTTP response status line and header fields. The returned integer is the HTTP status code, such as 200, 404, or 500. A return value of -1 means that no HTTP response was received because a transport or protocol error occurred.
After this method returns a status code, inspect ResponseHeader, ResponseStatusCode, ResponseStatusText, and the response-header access methods. If the response has a body, read it with ReadRespBodyString, ReadRespBd, ReadRespBodyStream, or another appropriate body-reading method.
HEAD response. A 204 No Content response is handled as a successful empty body.ReadResponseHeaderAsync (1)
function ReadResponseHeaderAsync: TChilkatBase;
Creates an asynchronous task to call the ReadResponseHeader method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
ReadRespSb
function ReadRespSb(responseBody: TChilkatBase): Boolean;
Reads the response body as text into the StringBuilder in responseBody, replacing its previous contents. Call this after ReadResponseHeader.
HEAD response. A 204 No Content response is handled as a successful empty body.Returns True for success, False for failure.
ReadRespSbAsync (1)
// Return value is a TTask object.
function ReadRespSbAsync(responseBody: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the ReadRespSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
RemoveHeader
Removes all request headers named by name from the request level selected by PartSelector.
Header-name matching is case-insensitive, and all matching occurrences are removed.
Returns True for success, False for failure.
RemoveQueryParam
Removes all query parameters whose name matches name.
Parameter-name matching is case-sensitive. All parameters having the exact name are removed. A True return value indicates that the operation completed successfully; it does not guarantee that a matching parameter existed.
Returns True for success, False for failure.
ResponseHdrByName
Returns the value of the response header field named by name. HTTP header field names are case-insensitive.
NumResponseHeaders, ResponseHdrName, and ResponseHdrValue to enumerate every field occurrence.If the response contains the same field more than once, this method returns the first matching value. Enumerate the header collection to obtain all occurrences, especially for fields such as Set-Cookie.
Returns True for success, False for failure.
ResponseHdrName
Returns the field name of the response header at zero-based index index. Valid indexes range from 0 through NumResponseHeaders minus one.
Enumeration preserves the response-field order and the field-name casing received from the server. Repeated fields occupy separate indexes.
Returns True for success, False for failure.
ResponseHdrValue
Returns the field value of the response header at zero-based index index. Use the same index with ResponseHdrName to obtain the corresponding field name.
Repeated response fields occupy separate indexes and are returned in received order.
Returns True for success, False for failure.
SendReqBd
function SendReqBd(const httpVerb: string;
const uriPath: string;
body: TChilkatBase): Boolean;
Sends a request whose binary body is read from the BinData in body.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqBdAsync (1)
// Return value is a TTask object.
function SendReqBdAsync(const httpVerb: string;
const uriPath: string;
body: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the SendReqBd method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqFormUrlEncoded
const uriPath: string): Boolean;
Sends an application/x-www-form-urlencoded request. The request body is built from the parameters added with AddQueryParam or AddQueryParams. Any manually supplied Content-Type value is replaced with application/x-www-form-urlencoded.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Parameters written directly in uriPath remain in the URL query string. Parameters stored through AddQueryParam, AddQueryParamSb, or AddQueryParams are encoded into the form body. After the form request is sent, this stored parameter collection is cleared.
Content-Type to application/x-www-form-urlencoded. That request-header value remains configured for later requests until it is replaced or cleared.Returns True for success, False for failure.
SendReqFormUrlEncodedAsync (1)
function SendReqFormUrlEncodedAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the SendReqFormUrlEncoded method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqMultipart
const uriPath: string): Boolean;
Sends a multipart request using the parts configured with PartSelector, AddHeader, and the multipart-body methods.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.multipart/form-data.The request fails if no multipart subparts are configured.
Returns True for success, False for failure.
SendReqMultipartAsync (1)
function SendReqMultipartAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the SendReqMultipart method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqNoBody
const uriPath: string): Boolean;
Sends a request without a request body.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqNoBodyAsync (1)
function SendReqNoBodyAsync(const httpVerb: string;
const uriPath: string): TChilkatBase;
Creates an asynchronous task to call the SendReqNoBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqSb
function SendReqSb(const httpVerb: string;
const uriPath: string;
bodySb: TChilkatBase): Boolean;
Sends a request whose text body is read from the StringBuilder in bodySb. Set the request Content-Type header to identify the body format.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
SendReqSbAsync (1)
// Return value is a TTask object.
function SendReqSbAsync(const httpVerb: string;
const uriPath: string;
bodySb: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the SendReqSb method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqStreamBody
function SendReqStreamBody(const httpVerb: string;
const uriPath: string;
stream: TChilkatBase): Boolean;
Sends a request whose body is read from the Stream in stream. The stream may supply text or binary data; set the request Content-Type header as required by the API.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Returns True for success, False for failure.
SendReqStreamBodyAsync (1)
// Return value is a TTask object.
function SendReqStreamBodyAsync(const httpVerb: string;
const uriPath: string;
stream: TChilkatBase): TChilkatBase;
Creates an asynchronous task to call the SendReqStreamBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SendReqStringBody
const uriPath: string;
const bodyText: string): Boolean;
Sends a request whose text body is supplied in bodyText, such as JSON, XML, form-independent text, or another textual representation. Set the request Content-Type header to identify the body format expected by the server.
httpVerb is the HTTP method, such as GET, POST, or PUT. uriPath is the request path. This is a low-level send operation: after it succeeds, call ReadResponseHeader and then read the response body with the appropriate response method.
uriPath is the path and optional query portion of the URL, not a complete URL. For https://api.example.com/v1/items?limit=10, pass /v1/items?limit=10. The server name and port are established separately by Connect or UseConnection.Content-Type header; add the media type required by the API, such as application/json; charset=utf-8.Returns True for success, False for failure.
SendReqStringBodyAsync (1)
function SendReqStringBodyAsync(const httpVerb: string;
const uriPath: string;
const bodyText: string): TChilkatBase;
Creates an asynchronous task to call the SendReqStringBody method with the arguments provided.
Note: Async method event callbacks happen in the background thread. Accessing and updating UI elements existing in the main thread may require special considerations.
Returns nil on failure
SetAuthAws
function SetAuthAws(authProvider: TChilkatBase): Boolean;
Associates the AuthAws provider in authProvider with this REST object. Chilkat uses the provider to sign each AWS request after the request method, path, query parameters, headers, and body are known. The application does not need to construct the Authorization header manually.
Returns True for success, False for failure.
SetAuthAzureSas
function SetAuthAzureSas(authProvider: TChilkatBase): Boolean;
Associates the AuthAzureSAS provider in authProvider with this REST object. Chilkat automatically adds an Authorization: SharedAccessSignature ... header to subsequent requests.
Returns True for success, False for failure.
SetAuthAzureStorage
function SetAuthAzureStorage(authProvider: TChilkatBase): Boolean;
Associates the AuthAzureStorage provider in authProvider with this REST object. Chilkat automatically applies the Azure Storage authorization information required for each request.
Returns True for success, False for failure.
SetAuthBasic
const password: string): Boolean;
Configures HTTP Basic authentication using username as the username and password as the password. Chilkat automatically generates an Authorization: Basic ... header for subsequent requests.
AllowInsecureBasicAuth in UncommonOptions exists only for exceptional compatibility needs.Some APIs use an account ID, client ID, API key, token, or secret in place of a traditional username or password; follow the service documentation.
Authorization header when each request is composed and takes precedence over a value set through the Authorization property or AddHeader.Returns True for success, False for failure.
SetAuthBasicSecure
// password is a TSecureString object.
function SetAuthBasicSecure(username: TChilkatBase;
password: TChilkatBase): Boolean;
Configures HTTP Basic authentication using the SecureString objects in username and password for the username and password. The resulting request behavior is the same as SetAuthBasic.
SecureString reduces unnecessary exposure of the credential text in ordinary application strings. Basic authentication must still be protected by TLS.Authorization header when each request is composed and takes precedence over a manually configured Authorization value.Returns True for success, False for failure.
SetAuthGoogle
function SetAuthGoogle(authProvider: TChilkatBase): Boolean;
Associates the AuthGoogle provider in authProvider with this REST object. Chilkat uses the provider to add the Google authentication information needed by subsequent API requests.
Returns True for success, False for failure.
SetAuthOAuth1
function SetAuthOAuth1(authProvider: TChilkatBase;
useQueryParams: Boolean): Boolean;
Associates the OAuth1 provider in authProvider with this REST object for OAuth 1.0 or OAuth 1.0a request signing.
If useQueryParams is True, the OAuth parameters and signature are placed in the query string. If useQueryParams is False, they are placed in the Authorization header.
Returns True for success, False for failure.
SetAuthOAuth2
function SetAuthOAuth2(authProvider: TChilkatBase): Boolean;
Associates the OAuth2 provider in authProvider with this REST object. The provider must contain a valid access token. Chilkat then adds an Authorization: Bearer <access-token> header to each request.
The access token may be obtained through an OAuth flow or loaded from previously saved token data. Token acquisition, refresh, expiration, and scope requirements are determined by the authorization server.
AddHeader. Do not configure both approaches for the same request because they compete for the same Authorization header.OAuth2 object is consulted when each request is composed rather than copied at setup time. Keep it alive while the Rest object uses it. Changing its AccessToken changes the bearer token used by subsequent requests.Authorization value.Returns True for success, False for failure.
SetMultipartBodyBd
function SetMultipartBodyBd(bodyData: TChilkatBase): Boolean;
Sets the binary body of the multipart part identified by PartSelector from the BinData in bodyData.
Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodySb
function SetMultipartBodySb(bodySb: TChilkatBase): Boolean;
Sets the text body of the multipart part identified by PartSelector from the StringBuilder in bodySb.
Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodyStream
function SetMultipartBodyStream(stream: TChilkatBase): Boolean;
Uses the Stream in stream as the body source for the multipart part identified by PartSelector.
Stream object alive. It is read from its current position and must be reset before reusing it for another upload.Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetMultipartBodyString
Sets the text body of the multipart part identified by PartSelector to bodyText.
AddHeader while the part is selected to set its Content-Type, Content-Disposition, and other part headers.Setting the body creates the selected part when it does not already exist. Part numbers do not need to be created consecutively.
Returns True for success, False for failure.
SetResponseBodyStream
function SetResponseBodyStream(expectedStatus: Integer;
autoSetStreamCharset: Boolean;
responseStream: TChilkatBase): Boolean;
Configures a Stream destination for response bodies received by the full-request convenience methods. The body is written to responseStream only when the response status code matches expectedStatus.
If streaming occurs successfully, a string-returning full-request method returns OK. If streaming was selected but writing the body fails, it returns FAIL. If the status code does not match expectedStatus, the body is not streamed and remains available as the method's normal response text.
If autoSetStreamCharset is True and the response is textual, the destination stream's StringCharset is set from the response Content-Type charset when available. autoSetStreamCharset is ignored for binary responses.
expectedStatus value | Status codes that are streamed |
|---|---|
200 | Only 200 |
-200 | 200 through 299 |
-210 | 210 through 219 |
ClearResponseBodyStream to restore normal response-body handling.For Boolean-returning full-request methods, successful streaming returns True. A StringBuilder response output receives OK; a BinData response output is cleared. If the status does not match expectedStatus, the stream is not written and the method returns the response through its normal output.
The configuration remains active for later full-request calls until ClearResponseBodyStream is called.
Returns True for success, False for failure.
UseConnection
function UseConnection(connection: TChilkatBase;
autoReconnect: Boolean): Boolean;
Uses the already-connected Socket in connection as the transport for REST requests. The socket may represent a direct TCP or TLS connection, an HTTP or SOCKS proxy connection, an SSH-tunneled channel, or another connection configured through the Socket API.
autoReconnect controls automatic reconnection for later requests when the connection is no longer usable.
Connect for ordinary direct connections. Use UseConnection when the connection requires advanced Socket configuration.Rest object retains and operates on the supplied Socket. Keep the Socket object alive while it is attached. Calling Disconnect disconnects it; with autoReconnect set to True, a later request can reconnect the same Socket object.Returns True for success, False for failure.