---
product: Chilkat
product_version: 11.7.0
language: c
language_label: C
class: Rest
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/c_CkRestRef.html
---
# Chilkat Rest — C — v11.7.0

> Chilkat 11.7.0 · language=c · class=Rest
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/Rest.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/guide.md`.

## Purpose

**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**

Build REST requests with explicit paths, headers, query parameters, request bodies, content types, and HTTP methods.

**Connection reuse**

Connect once and send multiple requests over the same underlying connection when appropriate.

**Authentication support**

Work with bearer tokens, OAuth2, AWS-style signing, Azure and Google auth helpers, and other service-specific authentication patterns.

**Request bodies and multipart**

Send JSON, XML, text, binary data, form parameters, multipart requests, streams, and file-based request bodies.

**Response handling**

Read response bodies as strings, bytes, streams, JSON, XML, or `StringBuilder` content, and inspect status codes and headers.

**Diagnostics and debugging**

Use detailed error text, raw request generation, response headers, connection state, and verbose diagnostics to troubleshoot API behavior.

**Choosing the right class:** Use `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`.

**Stateful request configuration:** Request headers, ordinary query parameters, path substitutions, multipart parts, and authentication settings remain associated with the `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.

**Low-level response workflow:** After a `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.

**Redirects and cookies:** The `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.

For an extended overview, see [Rest Class Overview](https://www.chilkatsoft.com/rest_class_overview.asp).

## Object creation, unlocking and error handling

**Create/Dispose**

```c
HCkRest instance = CkRest_Create();
// ...
CkRest_Dispose(instance);
```

`HCkRest CkRest_Create(void);`

Creates an instance of the HCkRest object and returns a handle ("void \*" pointer). The handle is passed in the 1st argument for the functions listed on this page.

`void CkRest_Dispose(HCkRest handle);`

Objects created by calling CkRest_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkRest_Dispose.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in C.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `void CkRest_getDebugLogFilePath(HCkRest cHandle, HCkString retval); void CkRest_putDebugLogFilePath(HCkRest cHandle, const char *newVal); const char *CkRest_debugLogFilePath(HCkRest cHandle);` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `void CkRest_getLastErrorHtml(HCkRest cHandle, HCkString retval); const char *CkRest_lastErrorHtml(HCkRest cHandle);` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `void CkRest_getLastErrorText(HCkRest cHandle, HCkString retval); const char *CkRest_lastErrorText(HCkRest cHandle);` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `void CkRest_getLastErrorXml(HCkRest cHandle, HCkString retval); const char *CkRest_lastErrorXml(HCkRest cHandle);` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `BOOL CkRest_getLastMethodSuccess(HCkRest cHandle); void CkRest_putLastMethodSuccess(HCkRest cHandle, BOOL newVal);` | read/write | Indicates the success or failure of the most recent method call: `TRUE` means success, `FALSE` means failure. |
| `Utf8` | `BOOL CkRest_getUtf8(HCkRest cHandle); void CkRest_putUtf8(HCkRest cHandle, BOOL newVal);` | read/write | When set to `TRUE`, all `const char *` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `BOOL CkRest_getVerboseLogging(HCkRest cHandle); void CkRest_putVerboseLogging(HCkRest cHandle, BOOL newVal);` | read/write | If set to `TRUE`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `void CkRest_getVersion(HCkRest cHandle, HCkString retval); const char *CkRest_version(HCkRest cHandle);` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `AllowHeaderFolding` | property, read/write | `BOOL CkRest_getAllowHeaderFolding(HCkRest cHandle); void CkRest_putAllowHeaderFolding(HCkRest cHandle, BOOL newVal);` |
| `AllowHeaderQB` | property, read/write | `BOOL CkRest_getAllowHeaderQB(HCkRest cHandle); void CkRest_putAllowHeaderQB(HCkRest cHandle, BOOL newVal);` |
| `Authorization` | property, read/write | `void CkRest_getAuthorization(HCkRest cHandle, HCkString retval); void CkRest_putAuthorization(HCkRest cHandle, const char *newVal); const char *CkRest_authorization(HCkRest cHandle);` |
| `ConnectFailReason` | property, read-only | `int CkRest_getConnectFailReason(HCkRest cHandle);` |
| `ConnectTimeoutMs` | property, read/write | `int CkRest_getConnectTimeoutMs(HCkRest cHandle); void CkRest_putConnectTimeoutMs(HCkRest cHandle, int newVal);` |
| `DebugMode` | property, read/write | `BOOL CkRest_getDebugMode(HCkRest cHandle); void CkRest_putDebugMode(HCkRest cHandle, BOOL newVal);` |
| `EnableSecrets` | property, read/write | `BOOL CkRest_getEnableSecrets(HCkRest cHandle); void CkRest_putEnableSecrets(HCkRest cHandle, BOOL newVal);` |
| `HeartbeatMs` | property, read/write | `int CkRest_getHeartbeatMs(HCkRest cHandle); void CkRest_putHeartbeatMs(HCkRest cHandle, int newVal);` |
| `Host` | property, read/write | `void CkRest_getHost(HCkRest cHandle, HCkString retval); void CkRest_putHost(HCkRest cHandle, const char *newVal); const char *CkRest_host(HCkRest cHandle);` |
| `IdleTimeoutMs` | property, read/write | `int CkRest_getIdleTimeoutMs(HCkRest cHandle); void CkRest_putIdleTimeoutMs(HCkRest cHandle, int newVal);` |
| `LastRedirectUrl` | property, read-only | `void CkRest_getLastRedirectUrl(HCkRest cHandle, HCkString retval); const char *CkRest_lastRedirectUrl(HCkRest cHandle);` |
| `LastRequestHeader` | property, read-only | `void CkRest_getLastRequestHeader(HCkRest cHandle, HCkString retval); const char *CkRest_lastRequestHeader(HCkRest cHandle);` |
| `LastRequestStartLine` | property, read-only | `void CkRest_getLastRequestStartLine(HCkRest cHandle, HCkString retval); const char *CkRest_lastRequestStartLine(HCkRest cHandle);` |
| `NumResponseHeaders` | property, read-only | `int CkRest_getNumResponseHeaders(HCkRest cHandle);` |
| `PartSelector` | property, read/write | `void CkRest_getPartSelector(HCkRest cHandle, HCkString retval); void CkRest_putPartSelector(HCkRest cHandle, const char *newVal); const char *CkRest_partSelector(HCkRest cHandle);` |
| `PercentDoneOnSend` | property, read/write | `BOOL CkRest_getPercentDoneOnSend(HCkRest cHandle); void CkRest_putPercentDoneOnSend(HCkRest cHandle, BOOL newVal);` |
| `ResponseHeader` | property, read-only | `void CkRest_getResponseHeader(HCkRest cHandle, HCkString retval); const char *CkRest_responseHeader(HCkRest cHandle);` |
| `ResponseStatusCode` | property, read-only | `int CkRest_getResponseStatusCode(HCkRest cHandle);` |
| `ResponseStatusText` | property, read-only | `void CkRest_getResponseStatusText(HCkRest cHandle, HCkString retval); const char *CkRest_responseStatusText(HCkRest cHandle);` |
| `StreamNonChunked` | property, read/write | `BOOL CkRest_getStreamNonChunked(HCkRest cHandle); void CkRest_putStreamNonChunked(HCkRest cHandle, BOOL newVal);` |
| `UncommonOptions` | property, read/write | `void CkRest_getUncommonOptions(HCkRest cHandle, HCkString retval); void CkRest_putUncommonOptions(HCkRest cHandle, const char *newVal); const char *CkRest_uncommonOptions(HCkRest cHandle);` |
| `AddHeader` | method | `BOOL CkRest_AddHeader(HCkRest cHandle, const char *name, const char *value);` |
| `AddMwsSignature` | method | `BOOL CkRest_AddMwsSignature(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *domain, const char *mwsSecretKey);` |
| `AddPathParam` | method | `BOOL CkRest_AddPathParam(HCkRest cHandle, const char *name, const char *value);` |
| `AddQueryParam` | method | `BOOL CkRest_AddQueryParam(HCkRest cHandle, const char *name, const char *value);` |
| `AddQueryParams` | method | `BOOL CkRest_AddQueryParams(HCkRest cHandle, const char *queryString);` |
| `AddQueryParamSb` | method | `BOOL CkRest_AddQueryParamSb(HCkRest cHandle, const char *name, HCkStringBuilder value);` |
| `ClearAllHeaders` | method | `BOOL CkRest_ClearAllHeaders(HCkRest cHandle);` |
| `ClearAllParts` | method | `BOOL CkRest_ClearAllParts(HCkRest cHandle);` |
| `ClearAllPathParams` | method | `BOOL CkRest_ClearAllPathParams(HCkRest cHandle);` |
| `ClearAllQueryParams` | method | `BOOL CkRest_ClearAllQueryParams(HCkRest cHandle);` |
| `ClearAuth` | method | `BOOL CkRest_ClearAuth(HCkRest cHandle);` |
| `ClearResponseBodyStream` | method | `void CkRest_ClearResponseBodyStream(HCkRest cHandle);` |
| `Connect` | method | `BOOL CkRest_Connect(HCkRest cHandle, const char *hostname, int port, BOOL tls, BOOL autoReconnect);` |
| `Disconnect` | method | `BOOL CkRest_Disconnect(HCkRest cHandle, int maxWaitMs);` |
| `FullRequestBd` | method | `BOOL CkRest_FullRequestBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData, HCkStringBuilder responseBody);` |
| `FullRequestFormUrlEncoded` | method | `BOOL CkRest_FullRequestFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr); const char *CkRest_fullRequestFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `FullRequestMultipart` | method | `BOOL CkRest_FullRequestMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr); const char *CkRest_fullRequestMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `FullRequestNoBody` | method | `BOOL CkRest_FullRequestNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr); const char *CkRest_fullRequestNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `FullRequestNoBodyBd` | method | `BOOL CkRest_FullRequestNoBodyBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData);` |
| `FullRequestNoBodySb` | method | `BOOL CkRest_FullRequestNoBodySb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder sb);` |
| `FullRequestSb` | method | `BOOL CkRest_FullRequestSb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder requestBody, HCkStringBuilder responseBody);` |
| `FullRequestStream` | method | `BOOL CkRest_FullRequestStream(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream, HCkString outStr); const char *CkRest_fullRequestStream(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);` |
| `FullRequestString` | method | `BOOL CkRest_FullRequestString(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText, HCkString outStr); const char *CkRest_fullRequestString(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);` |
| `GetLastDebugRequest` | method | `BOOL CkRest_GetLastDebugRequest(HCkRest cHandle, HCkBinData bd);` |
| `GetLastJsonData` | method | `void CkRest_GetLastJsonData(HCkRest cHandle, HCkJsonObject json);` |
| `LoadTaskCaller` | method | `BOOL CkRest_LoadTaskCaller(HCkRest cHandle, HCkTask task);` |
| `ReadRespBd` | method | `BOOL CkRest_ReadRespBd(HCkRest cHandle, HCkBinData responseBody);` |
| `ReadRespBodyStream` | method | `BOOL CkRest_ReadRespBodyStream(HCkRest cHandle, HCkStream stream, BOOL autoSetStreamCharset);` |
| `ReadRespBodyString` | method | `BOOL CkRest_ReadRespBodyString(HCkRest cHandle, HCkString outStr); const char *CkRest_readRespBodyString(HCkRest cHandle);` |
| `ReadRespChunkBd` | method | `int CkRest_ReadRespChunkBd(HCkRest cHandle, int minSize, HCkBinData bd);` |
| `ReadResponseHeader` | method | `int CkRest_ReadResponseHeader(HCkRest cHandle);` |
| `ReadRespSb` | method | `BOOL CkRest_ReadRespSb(HCkRest cHandle, HCkStringBuilder responseBody);` |
| `RemoveHeader` | method | `BOOL CkRest_RemoveHeader(HCkRest cHandle, const char *name);` |
| `RemoveQueryParam` | method | `BOOL CkRest_RemoveQueryParam(HCkRest cHandle, const char *name);` |
| `ResponseHdrByName` | method | `BOOL CkRest_ResponseHdrByName(HCkRest cHandle, const char *name, HCkString outStr); const char *CkRest_responseHdrByName(HCkRest cHandle, const char *name);` |
| `ResponseHdrName` | method | `BOOL CkRest_ResponseHdrName(HCkRest cHandle, int index, HCkString outStr); const char *CkRest_responseHdrName(HCkRest cHandle, int index);` |
| `ResponseHdrValue` | method | `BOOL CkRest_ResponseHdrValue(HCkRest cHandle, int index, HCkString outStr); const char *CkRest_responseHdrValue(HCkRest cHandle, int index);` |
| `SendReqBd` | method | `BOOL CkRest_SendReqBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData body);` |
| `SendReqFormUrlEncoded` | method | `BOOL CkRest_SendReqFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `SendReqMultipart` | method | `BOOL CkRest_SendReqMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `SendReqNoBody` | method | `BOOL CkRest_SendReqNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath);` |
| `SendReqSb` | method | `BOOL CkRest_SendReqSb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder bodySb);` |
| `SendReqStreamBody` | method | `BOOL CkRest_SendReqStreamBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);` |
| `SendReqStringBody` | method | `BOOL CkRest_SendReqStringBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);` |
| `SetAuthAws` | method | `BOOL CkRest_SetAuthAws(HCkRest cHandle, HCkAuthAws authProvider);` |
| `SetAuthAzureSas` | method | `BOOL CkRest_SetAuthAzureSas(HCkRest cHandle, HCkAuthAzureSAS authProvider);` |
| `SetAuthAzureStorage` | method | `BOOL CkRest_SetAuthAzureStorage(HCkRest cHandle, HCkAuthAzureStorage authProvider);` |
| `SetAuthBasic` | method | `BOOL CkRest_SetAuthBasic(HCkRest cHandle, const char *username, const char *password);` |
| `SetAuthBasicSecure` | method | `BOOL CkRest_SetAuthBasicSecure(HCkRest cHandle, HCkSecureString username, HCkSecureString password);` |
| `SetAuthGoogle` | method | `BOOL CkRest_SetAuthGoogle(HCkRest cHandle, HCkAuthGoogle authProvider);` |
| `SetAuthOAuth1` | method | `BOOL CkRest_SetAuthOAuth1(HCkRest cHandle, HCkOAuth1 authProvider, BOOL useQueryParams);` |
| `SetAuthOAuth2` | method | `BOOL CkRest_SetAuthOAuth2(HCkRest cHandle, HCkOAuth2 authProvider);` |
| `SetMultipartBodyBd` | method | `BOOL CkRest_SetMultipartBodyBd(HCkRest cHandle, HCkBinData bodyData);` |
| `SetMultipartBodySb` | method | `BOOL CkRest_SetMultipartBodySb(HCkRest cHandle, HCkStringBuilder bodySb);` |
| `SetMultipartBodyStream` | method | `BOOL CkRest_SetMultipartBodyStream(HCkRest cHandle, HCkStream stream);` |
| `SetMultipartBodyString` | method | `BOOL CkRest_SetMultipartBodyString(HCkRest cHandle, const char *bodyText);` |
| `SetResponseBodyStream` | method | `BOOL CkRest_SetResponseBodyStream(HCkRest cHandle, int expectedStatus, BOOL autoSetStreamCharset, HCkStream responseStream);` |
| `UseConnection` | method | `BOOL CkRest_UseConnection(HCkRest cHandle, HCkSocket connection, BOOL autoReconnect);` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### Rest.AllowHeaderFolding

`Chilkat 11.7.0 · c · Rest · AllowHeaderFolding · property · read/write · since 9.5.0.63`

```c
BOOL CkRest_getAllowHeaderFolding(HCkRest cHandle);
void CkRest_putAllowHeaderFolding(HCkRest cHandle, BOOL newVal);
```

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.

**Modern HTTP compatibility:** Obsolete HTTP line folding is rejected by some servers and signing systems. Set this property to `FALSE` when the service requires unfolded header lines, as is common for canonicalized request signatures.

### Rest.AllowHeaderQB

`Chilkat 11.7.0 · c · Rest · AllowHeaderQB · property · read/write · since 9.5.0.59`

```c
BOOL CkRest_getAllowHeaderQB(HCkRest cHandle);
void CkRest_putAllowHeaderQB(HCkRest cHandle, BOOL newVal);
```

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.

**Compatibility feature:** RFC 2047 encoded words originated in Internet message headers. Use this behavior only when the target HTTP service expects it; many APIs instead require ASCII header values or a service-specific encoding.

### Rest.Authorization

`Chilkat 11.7.0 · c · Rest · Authorization · property · read/write · since 9.5.0.58`

```c
void CkRest_getAuthorization(HCkRest cHandle, HCkString retval);
void CkRest_putAuthorization(HCkRest cHandle, const char *newVal);
const char *CkRest_authorization(HCkRest cHandle);
```

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:`.

**Authentication helpers:** For generated authentication, prefer the appropriate `SetAuth*` method. A configured authentication provider may generate or replace the Authorization header when the request is sent.

**Provider precedence:** When a `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.

### Rest.ConnectFailReason

`Chilkat 11.7.0 · c · Rest · ConnectFailReason · property · read-only · since 9.5.0.58`

```c
int CkRest_getConnectFailReason(HCkRest cHandle);
```

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 |

**Detailed diagnostics:** Use the code as a category and inspect `LastErrorText` for the full failure context.

**Reset after success:** A successful `Connect` resets this property to `0`. HTTP response properties are separate and are not cleared by a later failed connection attempt.

### Rest.ConnectTimeoutMs

`Chilkat 11.7.0 · c · Rest · ConnectTimeoutMs · property · read/write · since 9.5.0.71`

```c
int CkRest_getConnectTimeoutMs(HCkRest cHandle);
void CkRest_putConnectTimeoutMs(HCkRest cHandle, int newVal);
```

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.

**Related timeout:** Use `IdleTimeoutMs` to control how long an established operation may remain without send or receive progress.

The default is `30000` milliseconds.

### Rest.DebugMode

`Chilkat 11.7.0 · c · Rest · DebugMode · property · read/write · since 9.5.0.77`

```c
BOOL CkRest_getDebugMode(HCkRest cHandle);
void CkRest_putDebugMode(HCkRest cHandle, BOOL newVal);
```

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`.

**Safe request inspection:** This is useful for validating signing, headers, query strings, multipart formatting, and body encoding without contacting the server. The captured request may contain secrets.

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.

### Rest.EnableSecrets

`Chilkat 11.7.0 · c · Rest · EnableSecrets · property · read/write · since 11.5.0`

```c
BOOL CkRest_getEnableSecrets(HCkRest cHandle);
void CkRest_putEnableSecrets(HCkRest cHandle, BOOL newVal);
```

**Full documentation for this property (same in every language):** [More Detailed Information About EnableSecrets](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/secret_specification_strings.md)

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`.

**Why use secret resolution:** It avoids embedding long-lived credentials directly in source code, configuration files, command lines, or logs. The requested secret must already exist in the platform credential store.

### Rest.HeartbeatMs

`Chilkat 11.7.0 · c · Rest · HeartbeatMs · property · read/write · since 9.5.0.58`

```c
int CkRest_getHeartbeatMs(HCkRest cHandle);
void CkRest_putHeartbeatMs(HCkRest cHandle, int newVal);
```

**Full documentation for this property (same in every language):** [Event Callback Examples](https://www.chilkatsoft.com/ai-docs/v/11.7.0/articles/event_callback_examples.md)

Controls the interval, in milliseconds, between `AbortCheck` event callbacks during supported long-running operations. The default is `0`, which disables periodic AbortCheck callbacks.

**Choosing an interval:** A smaller value makes cancellation more responsive but causes callbacks more frequently.

### Rest.Host

`Chilkat 11.7.0 · c · Rest · Host · property · read/write · since 9.5.0.58`

```c
void CkRest_getHost(HCkRest cHandle, HCkString retval);
void CkRest_putHost(HCkRest cHandle, const char *newVal);
const char *CkRest_host(HCkRest cHandle);
```

Gets or sets the value of the HTTP `Host` request header.

**Usually automatic:** For a normal connection, Chilkat derives the Host header from the server established by `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`.

### Rest.IdleTimeoutMs

`Chilkat 11.7.0 · c · Rest · IdleTimeoutMs · property · read/write · since 9.5.0.58`

```c
int CkRest_getIdleTimeoutMs(HCkRest cHandle);
void CkRest_putIdleTimeoutMs(HCkRest cHandle, int newVal);
```

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.

**Not an overall deadline:** This is an inactivity timeout. An operation can run longer than this value as long as data continues to be sent or received.

A value of `0` disables the inactivity timeout.

### Rest.LastRedirectUrl

`Chilkat 11.7.0 · c · Rest · LastRedirectUrl · property · read-only · since 11.0.0`

```c
void CkRest_getLastRedirectUrl(HCkRest cHandle, HCkString retval);
const char *CkRest_lastRedirectUrl(HCkRest cHandle);
```

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.

**Relative redirects:** A Location value may be an absolute URL or a relative reference, depending on the server response.

**Redirect handling:** The value is the response Location field as received. `Rest` does not automatically follow the redirect; send a new request explicitly, reconnecting first if the target host changes.

### Rest.LastRequestHeader

`Chilkat 11.7.0 · c · Rest · LastRequestHeader · property · read-only · since 9.5.0.58`

```c
void CkRest_getLastRequestHeader(HCkRest cHandle, HCkString retval);
const char *CkRest_lastRequestHeader(HCkRest cHandle);
```

Returns the HTTP header fields from the most recently composed request, excluding the request line. The request line is available separately in `LastRequestStartLine`.

**Sensitive data:** The header block may contain credentials, bearer tokens, cookies, or signatures. Avoid writing it to logs unless sensitive values are redacted.

A failed `Connect` does not clear this value. It continues to describe the last request that was composed and sent.

### Rest.LastRequestStartLine

`Chilkat 11.7.0 · c · Rest · LastRequestStartLine · property · read-only · since 9.5.0.58`

```c
void CkRest_getLastRequestStartLine(HCkRest cHandle, HCkString retval);
const char *CkRest_lastRequestStartLine(HCkRest cHandle);
```

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.

### Rest.NumResponseHeaders

`Chilkat 11.7.0 · c · Rest · NumResponseHeaders · property · read-only · since 9.5.0.58`

```c
int CkRest_getNumResponseHeaders(HCkRest cHandle);
```

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.

### Rest.PartSelector

`Chilkat 11.7.0 · c · Rest · PartSelector · property · read/write · since 9.5.0.58`

```c
void CkRest_getPartSelector(HCkRest cHandle, HCkString retval);
void CkRest_putPartSelector(HCkRest cHandle, const char *newVal);
const char *CkRest_partSelector(HCkRest cHandle);
```

Selects the multipart entity or part targeted by multipart-building operations such as `AddHeader`, `RemoveHeader`, and the `SetMultipartBody*` methods.

| Value | Selected target |
| :--- | :--- |
| (empty) | 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 |

**Multipart indexes:** PartSelector uses one-based part numbers, unlike most Chilkat indexed accessors. Reset it to the empty string before modifying top-level request headers.

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.

### Rest.PercentDoneOnSend

`Chilkat 11.7.0 · c · Rest · PercentDoneOnSend · property · read/write · since 9.5.0.58`

```c
BOOL CkRest_getPercentDoneOnSend(HCkRest cHandle);
void CkRest_putPercentDoneOnSend(HCkRest cHandle, BOOL newVal);
```

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.

**A known total is required:** Percentage can be calculated only when the total byte count is known. For example, a chunked response may not provide a total response length.

### Rest.ResponseHeader

`Chilkat 11.7.0 · c · Rest · ResponseHeader · property · read-only · since 9.5.0.58`

```c
void CkRest_getResponseHeader(HCkRest cHandle, HCkString retval);
const char *CkRest_responseHeader(HCkRest cHandle);
```

Returns the HTTP response header fields from the most recently received response, excluding the status line.

**Status line:** The numeric status and reason text are available through `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.

### Rest.ResponseStatusCode

`Chilkat 11.7.0 · c · Rest · ResponseStatusCode · property · read-only · since 9.5.0.58`

```c
int CkRest_getResponseStatusCode(HCkRest cHandle);
```

Returns the numeric HTTP status code from the most recently received response, such as `200`, `404`, or `503`.

**HTTP status versus method success:** Receiving an HTTP error status such as `400` or `404` is still a completed HTTP exchange. Inspect `ResponseStatusCode` and the response body to determine the API-level result.

**Last completed exchange:** A failed `Connect` does not clear this property. It continues to report the status of the last HTTP response that was actually received.

### Rest.ResponseStatusText

`Chilkat 11.7.0 · c · Rest · ResponseStatusText · property · read-only · since 9.5.0.58`

```c
void CkRest_getResponseStatusText(HCkRest cHandle, HCkString retval);
const char *CkRest_responseStatusText(HCkRest cHandle);
```

Returns the reason phrase associated with the most recently received HTTP status code, such as `OK` or `Not Found`.

**Reason phrases are informational:** Applications should make decisions from the numeric status code. A reason phrase may be empty or may vary by server.

**Last completed exchange:** A failed `Connect` does not clear this property; it remains associated with the last received HTTP response.

### Rest.StreamNonChunked

`Chilkat 11.7.0 · c · Rest · StreamNonChunked · property · read/write · since 9.5.0.58`

```c
BOOL CkRest_getStreamNonChunked(HCkRest cHandle);
void CkRest_putStreamNonChunked(HCkRest cHandle, BOOL newVal);
```

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.

**Server compatibility:** Some HTTP servers and signing schemes require Content-Length and do not accept chunked request bodies; others support either form.

### Rest.UncommonOptions

`Chilkat 11.7.0 · c · Rest · UncommonOptions · property · read/write · since 9.5.0.80`

```c
void CkRest_getUncommonOptions(HCkRest cHandle, HCkString retval);
void CkRest_putUncommonOptions(HCkRest cHandle, const char *newVal);
const char *CkRest_uncommonOptions(HCkRest cHandle);
```

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. |

**Use sparingly:** Leave this property empty unless a documented interoperability requirement calls for one of these options. In particular, AllowInsecureBasicAuth can expose credentials to network observers.

## Methods

### Rest.AddHeader

`Chilkat 11.7.0 · c · Rest · AddHeader · method · since 9.5.0.58`

```c
BOOL CkRest_AddHeader(HCkRest cHandle, const char *name, const char *value);
```

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.

**HTTP header names:** Field names are case-insensitive. Pass only the field name in `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.

**Multipart selection:** Header operations apply to the entity selected by `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.

### Rest.AddMwsSignature

`Chilkat 11.7.0 · c · Rest · AddMwsSignature · method · since 9.5.0.66`

```c
BOOL CkRest_AddMwsSignature(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *domain, const char *mwsSecretKey);
```

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.

**Legacy MWS signing:** This method implements Amazon MWS signing and is not a general AWS request signer. For AWS services that use AWS authorization providers, use `SetAuthAws`.

Returns TRUE for success, FALSE for failure.

### Rest.AddPathParam

`Chilkat 11.7.0 · c · Rest · AddPathParam · method · since 9.5.0.70`

```c
BOOL CkRest_AddPathParam(HCkRest cHandle, const char *name, const char *value);
```

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`.

**Placeholders are application-defined:** The placeholder syntax is simply the text stored in `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.

**Reserved characters:** The replacement is not a general path-segment encoder. Spaces are percent-encoded, but reserved URI characters such as `/`, `?`, 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.

### Rest.AddQueryParam

`Chilkat 11.7.0 · c · Rest · AddQueryParam · method · since 9.5.0.58`

```c
BOOL CkRest_AddQueryParam(HCkRest cHandle, const char *name, const char *value);
```

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.

**Duplicate parameter names:** By default, adding the same name again replaces the existing value. To retain repeated names such as `tag=red&tag=blue`, include `AllowDuplicateQueryParams` in `UncommonOptions`.

**Encoding and lifetime:** `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.

### Rest.AddQueryParams

`Chilkat 11.7.0 · c · Rest · AddQueryParams · method · since 9.5.0.58`

```c
BOOL CkRest_AddQueryParams(HCkRest cHandle, const char *queryString);
```

Adds multiple query parameters from the query-string text in `queryString`. Use the form `field1=value1&field2=value2&field3=value3`.

**Encoding responsibility:** The values in `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.

### Rest.AddQueryParamSb

`Chilkat 11.7.0 · c · Rest · AddQueryParamSb · method · since 9.5.0.62`

```c
BOOL CkRest_AddQueryParamSb(HCkRest cHandle, const char *name, HCkStringBuilder value);
```

Adds or replaces a query-string parameter named by `name`. The parameter value is read from the `StringBuilder` in `value`.

**Duplicate parameter names:** By default, the same name is replaced. Include `AllowDuplicateQueryParams` in `UncommonOptions` to retain repeated names.

**Encoding and lifetime:** `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.

### Rest.ClearAllHeaders

`Chilkat 11.7.0 · c · Rest · ClearAllHeaders · method · since 9.5.0.58`

```c
BOOL CkRest_ClearAllHeaders(HCkRest cHandle);
```

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.

### Rest.ClearAllParts

`Chilkat 11.7.0 · c · Rest · ClearAllParts · method · since 9.5.0.64`

```c
BOOL CkRest_ClearAllParts(HCkRest cHandle);
```

Removes all multipart subparts from the request under construction. This is useful when reusing the same REST object after sending a multipart request.

**Scope:** This clears multipart parts; it does not by itself clear query parameters, path parameters, authentication settings, or ordinary top-level request headers.

This also resets `PartSelector` to the empty string and releases the configured multipart bodies and part streams.

Returns TRUE for success, FALSE for failure.

### Rest.ClearAllPathParams

`Chilkat 11.7.0 · c · Rest · ClearAllPathParams · method · since 9.5.0.70`

```c
BOOL CkRest_ClearAllPathParams(HCkRest cHandle);
```

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.

### Rest.ClearAllQueryParams

`Chilkat 11.7.0 · c · Rest · ClearAllQueryParams · method · since 9.5.0.58`

```c
BOOL CkRest_ClearAllQueryParams(HCkRest cHandle);
```

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.

### Rest.ClearAuth

`Chilkat 11.7.0 · c · Rest · ClearAuth · method · since 9.5.0.69`

```c
BOOL CkRest_ClearAuth(HCkRest cHandle);
```

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.

### Rest.ClearResponseBodyStream

`Chilkat 11.7.0 · c · Rest · ClearResponseBodyStream · method · since 9.5.0.58`

```c
void CkRest_ClearResponseBodyStream(HCkRest cHandle);
```

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.

### Rest.Connect

`Chilkat 11.7.0 · c · Rest · Connect · method · since 9.5.0.58`

```c
BOOL CkRest_Connect(HCkRest cHandle, const char *hostname, int port, BOOL tls, BOOL autoReconnect);
```

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 only:** `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.

**Advanced connections:** `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`.

**Reconnect behavior:** When `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.

**Result-state behavior:** A successful connection resets `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.

Async variant: `ConnectAsync` — same arguments, returns a `Task` (see Async variants below).

See also:

- [Auto-Reconnect Feature of Chilkat.Rest Explained](https://cknotes.com/auto-reconnect-feature-of-chilkat-rest-explained/)

### Rest.Disconnect

`Chilkat 11.7.0 · c · Rest · Disconnect · method · since 9.5.0.58`

```c
BOOL CkRest_Disconnect(HCkRest cHandle, int maxWaitMs);
```

Closes the current HTTP connection, if one is open. `maxWaitMs` is the maximum number of milliseconds to wait while attempting a clean shutdown.

**Tunneled connections:** When the REST connection uses an SSH tunnel, this closes the logical channel used by REST. It does not close the underlying SSH session itself.

**Socket supplied by UseConnection:** When the transport was supplied through `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.

Async variant: `DisconnectAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestBd

`Chilkat 11.7.0 · c · Rest · FullRequestBd · method · since 9.5.0.64`

```c
BOOL CkRest_FullRequestBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData, HCkStringBuilder responseBody);
```

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`.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `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.

Async variant: `FullRequestBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestFormUrlEncoded

`Chilkat 11.7.0 · c · Rest · FullRequestFormUrlEncoded · method · since 9.5.0.58`

```c
BOOL CkRest_FullRequestFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr);
const char *CkRest_fullRequestFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `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.

**Persistent Content-Type:** The method sets the top-level `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.

Async variant: `FullRequestFormUrlEncodedAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestMultipart

`Chilkat 11.7.0 · c · Rest · FullRequestMultipart · method · since 9.5.0.58`

```c
BOOL CkRest_FullRequestMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr);
const char *CkRest_fullRequestMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `400` or `404` is still a completed HTTP exchange. Inspect `ResponseStatusCode` and the response body to determine the API-level result.

**Multipart state:** Assigning a body to a selected part creates that part. Parts may be created out of numeric order, persist across multipart requests, and retain the generated boundary while the multipart structure remains configured. The default top-level media type is `multipart/form-data`.

The request fails if no multipart subparts are configured.

Returns TRUE for success, FALSE for failure.

Async variant: `FullRequestMultipartAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestNoBody

`Chilkat 11.7.0 · c · Rest · FullRequestNoBody · method · since 9.5.0.58`

```c
BOOL CkRest_FullRequestNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkString outStr);
const char *CkRest_fullRequestNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `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.

Async variant: `FullRequestNoBodyAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestNoBodyBd

`Chilkat 11.7.0 · c · Rest · FullRequestNoBodyBd · method · since 9.5.0.64`

```c
BOOL CkRest_FullRequestNoBodyBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData);
```

Sends a complete request without a request body and stores the binary response body in the `BinData` in `binData`, replacing its previous contents.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `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.

Async variant: `FullRequestNoBodyBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestNoBodySb

`Chilkat 11.7.0 · c · Rest · FullRequestNoBodySb · method · since 9.5.0.64`

```c
BOOL CkRest_FullRequestNoBodySb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder sb);
```

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`.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `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.

Async variant: `FullRequestNoBodySbAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestSb

`Chilkat 11.7.0 · c · Rest · FullRequestSb · method · since 9.5.0.62`

```c
BOOL CkRest_FullRequestSb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder requestBody, HCkStringBuilder responseBody);
```

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`.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `400` or `404` is still a completed HTTP exchange. Inspect `ResponseStatusCode` and the response body to determine the API-level result.

**Text encoding and Content-Type:** Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a `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.

Async variant: `FullRequestSbAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestStream

`Chilkat 11.7.0 · c · Rest · FullRequestStream · method · since 9.5.0.58`

```c
BOOL CkRest_FullRequestStream(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream, HCkString outStr);
const char *CkRest_fullRequestStream(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);
```

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.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `400` or `404` is still a completed HTTP exchange. Inspect `ResponseStatusCode` and the response body to determine the API-level result.

**Stream position:** The stream is read from its current position and is left consumed. Reusing the same stream without resetting its source or position sends only the unread remainder, which may be zero bytes.

Returns TRUE for success, FALSE for failure.

Async variant: `FullRequestStreamAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.FullRequestString

`Chilkat 11.7.0 · c · Rest · FullRequestString · method · since 9.5.0.58`

```c
BOOL CkRest_FullRequestString(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText, HCkString outStr);
const char *CkRest_fullRequestString(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);
```

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.

**Request path:** `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`.

**HTTP status versus method success:** Receiving an HTTP error status such as `400` or `404` is still a completed HTTP exchange. Inspect `ResponseStatusCode` and the response body to determine the API-level result.

**Text encoding and Content-Type:** Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a `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.

Async variant: `FullRequestStringAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.GetLastDebugRequest

`Chilkat 11.7.0 · c · Rest · GetLastDebugRequest · method · since 9.5.0.77`

```c
BOOL CkRest_GetLastDebugRequest(HCkRest cHandle, HCkBinData bd);
```

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.

**Diagnostic use:** Debug mode does not transmit the request. Treat captured requests as sensitive because they may contain authorization headers, cookies, tokens, or request-body credentials.

`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.

### Rest.GetLastJsonData

`Chilkat 11.7.0 · c · Rest · GetLastJsonData · method · since 11.0.0`

```c
void CkRest_GetLastJsonData(HCkRest cHandle, HCkJsonObject json);
```

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.

**Read immediately:** Call this immediately after the operation of interest because a later method call may replace the stored JSON data.

### Rest.LoadTaskCaller

`Chilkat 11.7.0 · c · Rest · LoadTaskCaller · method · since 9.5.0.80`

```c
BOOL CkRest_LoadTaskCaller(HCkRest cHandle, HCkTask task);
```

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.

**Async task relationship:** This method recovers the originating REST caller state from a task; it does not load arbitrary task data.

Returns TRUE for success, FALSE for failure.

### Rest.ReadRespBd

`Chilkat 11.7.0 · c · Rest · ReadRespBd · method · since 9.5.0.62`

```c
BOOL CkRest_ReadRespBd(HCkRest cHandle, HCkBinData responseBody);
```

Reads the response body as raw bytes into the `BinData` in `responseBody`, replacing its previous contents. Call this after `ReadResponseHeader`.

**Use for binary content:** Typical examples include images, archives, PDFs, encrypted data, and arbitrary file downloads.

**Read once:** A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.

**Responses without a body:** Do not call a body-reading method for a `HEAD` response. A `204 No Content` response is handled as a successful empty body.

Returns TRUE for success, FALSE for failure.

Async variant: `ReadRespBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.ReadRespBodyStream

`Chilkat 11.7.0 · c · Rest · ReadRespBodyStream · method · since 9.5.0.58`

```c
BOOL CkRest_ReadRespBodyStream(HCkRest cHandle, HCkStream stream, BOOL autoSetStreamCharset);
```

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.

**Large downloads:** A stream can write directly to a file or another destination, avoiding the need to buffer the entire response body in memory.

**Read once:** A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.

**Responses without a body:** Do not call a body-reading method for a `HEAD` response. A `204 No Content` response is handled as a successful empty body.

Returns TRUE for success, FALSE for failure.

Async variant: `ReadRespBodyStreamAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.ReadRespBodyString

`Chilkat 11.7.0 · c · Rest · ReadRespBodyString · method · since 9.5.0.58`

```c
BOOL CkRest_ReadRespBodyString(HCkRest cHandle, HCkString outStr);
const char *CkRest_readRespBodyString(HCkRest cHandle);
```

Reads the response body as text and returns it. Call this only after `ReadResponseHeader` has returned the response status code.

**Text versus binary:** Use this method for JSON, XML, HTML, and other textual responses. Use `ReadRespBd` or `ReadRespBodyStream` for binary or very large content.

**Read once:** A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.

**Responses without a body:** Do not call a body-reading method for a `HEAD` response. A `204 No Content` response is handled as a successful empty body.

Returns TRUE for success, FALSE for failure.

Async variant: `ReadRespBodyStringAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.ReadRespChunkBd

`Chilkat 11.7.0 · c · Rest · ReadRespChunkBd · method · since 10.1.0`

```c
int CkRest_ReadRespChunkBd(HCkRest cHandle, int minSize, HCkBinData bd);
```

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. |

**Incremental processing:** This method is useful when the application wants to process a long response progressively rather than buffer it all at once.

Async variant: `ReadRespChunkBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.ReadResponseHeader

`Chilkat 11.7.0 · c · Rest · ReadResponseHeader · method · since 9.5.0.58`

```c
int CkRest_ReadResponseHeader(HCkRest cHandle);
```

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.

**Do not infer body presence from the request method alone:** Whether a response body is present depends on the response status, request method, and response headers. For example, a GET commonly has a response body, while HEAD does not.

**Read once:** A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.

**Responses without a body:** Do not call a body-reading method for a `HEAD` response. A `204 No Content` response is handled as a successful empty body.

Async variant: `ReadResponseHeaderAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.ReadRespSb

`Chilkat 11.7.0 · c · Rest · ReadRespSb · method · since 9.5.0.62`

```c
BOOL CkRest_ReadRespSb(HCkRest cHandle, HCkStringBuilder responseBody);
```

Reads the response body as text into the `StringBuilder` in `responseBody`, replacing its previous contents. Call this after `ReadResponseHeader`.

**Read once:** A response body may be consumed by only one body-reading method. A second attempt fails immediately. Fully consume the body before sending another request on the same connection; otherwise unread bytes can prevent the next response header from being parsed correctly.

**Responses without a body:** Do not call a body-reading method for a `HEAD` response. A `204 No Content` response is handled as a successful empty body.

Returns TRUE for success, FALSE for failure.

Async variant: `ReadRespSbAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.RemoveHeader

`Chilkat 11.7.0 · c · Rest · RemoveHeader · method · since 9.5.0.58`

```c
BOOL CkRest_RemoveHeader(HCkRest cHandle, const char *name);
```

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.

### Rest.RemoveQueryParam

`Chilkat 11.7.0 · c · Rest · RemoveQueryParam · method · since 9.5.0.58`

```c
BOOL CkRest_RemoveQueryParam(HCkRest cHandle, const char *name);
```

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.

### Rest.ResponseHdrByName

`Chilkat 11.7.0 · c · Rest · ResponseHdrByName · method · since 9.5.0.58`

```c
BOOL CkRest_ResponseHdrByName(HCkRest cHandle, const char *name, HCkString outStr);
const char *CkRest_responseHdrByName(HCkRest cHandle, const char *name);
```

Returns the value of the response header field named by `name`. HTTP header field names are case-insensitive.

**Repeated response headers:** When the response can contain repeated fields, use `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.

### Rest.ResponseHdrName

`Chilkat 11.7.0 · c · Rest · ResponseHdrName · method · since 9.5.0.58`

```c
BOOL CkRest_ResponseHdrName(HCkRest cHandle, int index, HCkString outStr);
const char *CkRest_responseHdrName(HCkRest cHandle, int index);
```

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.

### Rest.ResponseHdrValue

`Chilkat 11.7.0 · c · Rest · ResponseHdrValue · method · since 9.5.0.58`

```c
BOOL CkRest_ResponseHdrValue(HCkRest cHandle, int index, HCkString outStr);
const char *CkRest_responseHdrValue(HCkRest cHandle, int index);
```

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.

### Rest.SendReqBd

`Chilkat 11.7.0 · c · Rest · SendReqBd · method · since 9.5.0.62`

```c
BOOL CkRest_SendReqBd(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData body);
```

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.

**Request path:** `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.

Async variant: `SendReqBdAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqFormUrlEncoded

`Chilkat 11.7.0 · c · Rest · SendReqFormUrlEncoded · method · since 9.5.0.58`

```c
BOOL CkRest_SendReqFormUrlEncoded(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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.

**Persistent Content-Type:** The method sets the top-level `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.

Async variant: `SendReqFormUrlEncodedAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqMultipart

`Chilkat 11.7.0 · c · Rest · SendReqMultipart · method · since 9.5.0.58`

```c
BOOL CkRest_SendReqMultipart(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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 state:** Assigning a body to a selected part creates that part. Parts may be created out of numeric order, persist across multipart requests, and retain the generated boundary while the multipart structure remains configured. The default top-level media type is `multipart/form-data`.

The request fails if no multipart subparts are configured.

Returns TRUE for success, FALSE for failure.

Async variant: `SendReqMultipartAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqNoBody

`Chilkat 11.7.0 · c · Rest · SendReqNoBody · method · since 9.5.0.58`

```c
BOOL CkRest_SendReqNoBody(HCkRest cHandle, const char *httpVerb, const char *uriPath);
```

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.

**Request path:** `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.

Async variant: `SendReqNoBodyAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqSb

`Chilkat 11.7.0 · c · Rest · SendReqSb · method · since 9.5.0.62`

```c
BOOL CkRest_SendReqSb(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder bodySb);
```

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.

**Request path:** `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`.

**Text encoding and Content-Type:** Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a `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.

Async variant: `SendReqSbAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqStreamBody

`Chilkat 11.7.0 · c · Rest · SendReqStreamBody · method · since 9.5.0.58`

```c
BOOL CkRest_SendReqStreamBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);
```

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.

**Request path:** `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`.

**Streaming:** The stream is consumed while the request is sent, which is useful when the body is too large to hold in memory.

**Stream position:** The stream is read from its current position and is left consumed. Reusing the same stream without resetting its source or position sends only the unread remainder, which may be zero bytes.

Returns TRUE for success, FALSE for failure.

Async variant: `SendReqStreamBodyAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SendReqStringBody

`Chilkat 11.7.0 · c · Rest · SendReqStringBody · method · since 9.5.0.58`

```c
BOOL CkRest_SendReqStringBody(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);
```

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.

**Request path:** `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`.

**Text encoding and Content-Type:** Unicode text is encoded as UTF-8. Generic string-body methods do not automatically add a `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.

Async variant: `SendReqStringBodyAsync` — same arguments, returns a `Task` (see Async variants below).

### Rest.SetAuthAws

`Chilkat 11.7.0 · c · Rest · SetAuthAws · method · since 9.5.0.58`

```c
BOOL CkRest_SetAuthAws(HCkRest cHandle, HCkAuthAws authProvider);
```

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.

**Request signing:** AWS signatures cover selected request components. Add all required headers and query parameters before sending the request so the generated signature matches the final request.

Returns TRUE for success, FALSE for failure.

### Rest.SetAuthAzureSas

`Chilkat 11.7.0 · c · Rest · SetAuthAzureSas · method · since 9.5.0.65`

```c
BOOL CkRest_SetAuthAzureSas(HCkRest cHandle, HCkAuthAzureSAS authProvider);
```

Associates the `AuthAzureSAS` provider in `authProvider` with this REST object. Chilkat automatically adds an `Authorization: SharedAccessSignature ...` header to subsequent requests.

**SAS terminology:** This method is for Azure services that use a Shared Access Signature in the Authorization header. It is distinct from a storage SAS token embedded in a URL query string.

Returns TRUE for success, FALSE for failure.

### Rest.SetAuthAzureStorage

`Chilkat 11.7.0 · c · Rest · SetAuthAzureStorage · method · since 9.5.0.58`

```c
BOOL CkRest_SetAuthAzureStorage(HCkRest cHandle, HCkAuthAzureStorage authProvider);
```

Associates the `AuthAzureStorage` provider in `authProvider` with this REST object. Chilkat automatically applies the Azure Storage authorization information required for each request.

**Azure Storage authentication:** The provider contains the storage account credentials and signing settings. Request-specific headers and the resource path are incorporated when the request is sent.

Returns TRUE for success, FALSE for failure.

### Rest.SetAuthBasic

`Chilkat 11.7.0 · c · Rest · SetAuthBasic · method · since 9.5.0.58`

```c
BOOL CkRest_SetAuthBasic(HCkRest cHandle, const char *username, const char *password);
```

Configures HTTP Basic authentication using `username` as the username and `password` as the password. Chilkat automatically generates an `Authorization: Basic ...` header for subsequent requests.

**Security requirement:** Basic authentication is an encoding scheme, not encryption. Use it only over TLS. By default, Chilkat blocks Basic authentication on an insecure remote connection; `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 precedence:** The Basic authentication provider generates the `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.

### Rest.SetAuthBasicSecure

`Chilkat 11.7.0 · c · Rest · SetAuthBasicSecure · method · since 9.5.0.71`

```c
BOOL CkRest_SetAuthBasicSecure(HCkRest cHandle, HCkSecureString username, HCkSecureString password);
```

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`.

**Credential handling:** `SecureString` reduces unnecessary exposure of the credential text in ordinary application strings. Basic authentication must still be protected by TLS.

**Authorization precedence:** The Basic authentication provider generates the `Authorization` header when each request is composed and takes precedence over a manually configured Authorization value.

Returns TRUE for success, FALSE for failure.

### Rest.SetAuthGoogle

`Chilkat 11.7.0 · c · Rest · SetAuthGoogle · method · since 9.5.0.58`

```c
BOOL CkRest_SetAuthGoogle(HCkRest cHandle, HCkAuthGoogle authProvider);
```

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.

### Rest.SetAuthOAuth1

`Chilkat 11.7.0 · c · Rest · SetAuthOAuth1 · method · since 9.5.0.58`

```c
BOOL CkRest_SetAuthOAuth1(HCkRest cHandle, HCkOAuth1 authProvider, BOOL useQueryParams);
```

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.

**Final request matters:** OAuth 1 signatures depend on the HTTP method, request URL, and parameters. Configure the request completely before sending it.

Returns TRUE for success, FALSE for failure.

### Rest.SetAuthOAuth2

`Chilkat 11.7.0 · c · Rest · SetAuthOAuth2 · method · since 9.5.0.59`

```c
BOOL CkRest_SetAuthOAuth2(HCkRest cHandle, HCkOAuth2 authProvider);
```

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.

**Manual bearer headers:** A bearer token can also be supplied with `AddHeader`. Do not configure both approaches for the same request because they compete for the same `Authorization` header.

**Provider lifetime:** The `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 precedence:** The provider-generated bearer header takes precedence over a manually configured `Authorization` value.

Returns TRUE for success, FALSE for failure.

### Rest.SetMultipartBodyBd

`Chilkat 11.7.0 · c · Rest · SetMultipartBodyBd · method · since 9.5.0.62`

```c
BOOL CkRest_SetMultipartBodyBd(HCkRest cHandle, HCkBinData bodyData);
```

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.

### Rest.SetMultipartBodySb

`Chilkat 11.7.0 · c · Rest · SetMultipartBodySb · method · since 9.5.0.62`

```c
BOOL CkRest_SetMultipartBodySb(HCkRest cHandle, HCkStringBuilder bodySb);
```

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.

### Rest.SetMultipartBodyStream

`Chilkat 11.7.0 · c · Rest · SetMultipartBodyStream · method · since 9.5.0.58`

```c
BOOL CkRest_SetMultipartBodyStream(HCkRest cHandle, HCkStream stream);
```

Uses the `Stream` in `stream` as the body source for the multipart part identified by `PartSelector`.

**Large multipart parts:** The stream is read while the request is sent, allowing a large file or generated body to be uploaded without first loading the entire part into memory.

**Object lifetime and position:** The selected part retains the stream as its body source until the multipart request is sent or the parts are cleared. Keep the `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.

### Rest.SetMultipartBodyString

`Chilkat 11.7.0 · c · Rest · SetMultipartBodyString · method · since 9.5.0.58`

```c
BOOL CkRest_SetMultipartBodyString(HCkRest cHandle, const char *bodyText);
```

Sets the text body of the multipart part identified by `PartSelector` to `bodyText`.

**Part metadata:** Use `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.

### Rest.SetResponseBodyStream

`Chilkat 11.7.0 · c · Rest · SetResponseBodyStream · method · since 9.5.0.58`

```c
BOOL CkRest_SetResponseBodyStream(HCkRest cHandle, int expectedStatus, BOOL autoSetStreamCharset, HCkStream responseStream);
```

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` |

**Resetting this behavior:** Call `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.

### Rest.UseConnection

`Chilkat 11.7.0 · c · Rest · UseConnection · method · since 9.5.0.58`

```c
BOOL CkRest_UseConnection(HCkRest cHandle, HCkSocket connection, BOOL autoReconnect);
```

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.

**When to use this method:** Use `Connect` for ordinary direct connections. Use `UseConnection` when the connection requires advanced Socket configuration.

**Socket lifetime:** The `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.

## Events and callbacks

This binding delivers progress information through callbacks (AbortCheck, PercentDone, ProgressInfo, TaskCompleted) rather than events. See `guide.md` for how to attach them in C.

## Async variants

Each returns a `Task` instead of the result and takes the same arguments as the synchronous method; run the task, wait for `Finished`, then read the result from the task. No new Async methods are added from 11.7.0 on.

```c
HCkTask CkRest_ConnectAsync(HCkRest cHandle, const char *hostname, int port, BOOL tls, BOOL autoReconnect);
HCkTask CkRest_DisconnectAsync(HCkRest cHandle, int maxWaitMs);
HCkTask CkRest_FullRequestBdAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData, HCkStringBuilder responseBody);
HCkTask CkRest_FullRequestFormUrlEncodedAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_FullRequestMultipartAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_FullRequestNoBodyAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_FullRequestNoBodyBdAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData binData);
HCkTask CkRest_FullRequestNoBodySbAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder sb);
HCkTask CkRest_FullRequestSbAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder requestBody, HCkStringBuilder responseBody);
HCkTask CkRest_FullRequestStreamAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);
HCkTask CkRest_FullRequestStringAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);
HCkTask CkRest_ReadRespBdAsync(HCkRest cHandle, HCkBinData responseBody);
HCkTask CkRest_ReadRespBodyStreamAsync(HCkRest cHandle, HCkStream stream, BOOL autoSetStreamCharset);
HCkTask CkRest_ReadRespBodyStringAsync(HCkRest cHandle);
HCkTask CkRest_ReadRespChunkBdAsync(HCkRest cHandle, int minSize, HCkBinData bd);
HCkTask CkRest_ReadResponseHeaderAsync(HCkRest cHandle);
HCkTask CkRest_ReadRespSbAsync(HCkRest cHandle, HCkStringBuilder responseBody);
HCkTask CkRest_SendReqBdAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkBinData body);
HCkTask CkRest_SendReqFormUrlEncodedAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_SendReqMultipartAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_SendReqNoBodyAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath);
HCkTask CkRest_SendReqSbAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStringBuilder bodySb);
HCkTask CkRest_SendReqStreamBodyAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, HCkStream stream);
HCkTask CkRest_SendReqStringBodyAsync(HCkRest cHandle, const char *httpVerb, const char *uriPath, const char *bodyText);
```

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `FullRequestBinary` | method | before 11.6.1 | — |
| `LastJsonData` | method | before 11.6.1 | — |
| `ReadRespBodyBinary` | method | before 11.6.1 | — |
| `RedirectUrl` | method | before 11.6.1 | — |
| `SendReqBinaryBody` | method | before 11.6.1 | — |
| `SetMultipartBodyBinary` | method | before 11.6.1 | — |

## Related classes

[`AuthAws`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/AuthAws.md), [`AuthAzureSAS`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/AuthAzureSAS.md), [`AuthAzureStorage`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/AuthAzureStorage.md), [`AuthGoogle`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/AuthGoogle.md), [`BinData`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/BinData.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/JsonObject.md), [`OAuth1`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/OAuth1.md), [`OAuth2`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/OAuth2.md), [`SecureString`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/SecureString.md), [`Socket`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/Socket.md), [`Stream`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/Stream.md), [`StringBuilder`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/StringBuilder.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/c/classes/Task.md)