Chilkat.Rest Class Overview
Chilkat.Rest is a lower-level HTTP/REST client for building, signing, sending, and reading REST requests over an established HTTP or HTTPS connection. It provides direct control over headers, query parameters, path parameters, request bodies, multipart requests, response streaming, authentication, debugging, and connection reuse.
What the Class Is Used For
Use Chilkat.Rest when an application needs precise control over REST-style HTTP communication. The class is especially useful when requests must be built incrementally, authenticated with provider-specific signing objects, sent over a pre-established socket, streamed, debugged before sending, or handled in separate send/read phases.
Build REST Requests
Add headers, query parameters, path parameters, body content, and multipart
parts before sending.
Send Full Requests
Use FullRequest* methods to send the request and
receive the complete response in one call.
Send and Read Separately
Use SendReq*, then
ReadResponseHeader, then a response-body method
when more control is needed.
Use Custom Connections
Connect directly with Connect, or use an existing
Socket connection for proxies, tunnels, TLS, or
advanced network scenarios.
Important URL distinction:
Connect takes only the hostname, not a full URL.
Request methods take only the URI path and optional query string, not a full URL.
For example, for https://api.example.com/v1/items?id=123,
connect to api.example.com, then request
/v1/items?id=123.
Typical Workflow
- Establish a connection with Connect(hostname, port, tls, autoReconnect), or provide an already-connected socket using UseConnection.
- Add authentication, if needed, using methods such as SetAuthBasic, SetAuthOAuth2, SetAuthAws, SetAuthAzureStorage, or SetAuthGoogle.
- Add request headers with AddHeader, query parameters with AddQueryParam, and path substitutions with AddPathParam.
- Choose a request method based on the request body type: no body, string, StringBuilder, binary bytes, BinData, stream, form-url-encoded, or multipart.
- Use a FullRequest* method for a one-call send/receive, or use a SendReq* method followed by explicit response-reading methods.
- Inspect ResponseStatusCode, ResponseStatusText, ResponseHeader, and response-header helper methods.
- For troubleshooting, check LastErrorText, ConnectFailReason, LastRequestStartLine, LastRequestHeader, and GetLastDebugRequest.
Core Concepts
| Concept | Meaning | Important Members |
|---|---|---|
| Connection First | A REST object sends requests over an existing connection. Connect directly to a host and port, or use a socket created elsewhere. | Connect, UseConnection, Disconnect |
| URI Path, Not Full URL | Request methods expect the path and optional query part only, such as /v1/files/123?alt=media. | FullRequestNoBody, FullRequestString, SendReqNoBody |
| Path Parameters | Named placeholders in request paths can be replaced before the request is sent. | AddPathParam, ClearAllPathParams |
| Query Parameters | Query parameters can be accumulated and automatically appended or used as form-url-encoded body content. | AddQueryParam, AddQueryParams, RemoveQueryParam, ClearAllQueryParams |
| FullRequest Methods | Convenience methods that send the request and read the complete response in one call. | FullRequestNoBody, FullRequestString, FullRequestBinary, FullRequestMultipart |
| Send/Read Methods | Lower-level methods that send the request first, then let the application read the response header and body separately. | SendReqNoBody, ReadResponseHeader, ReadRespBodyString, ReadRespBd |
| Multipart Parts | Multipart requests are built from sub-parts. The PartSelector identifies which part is being modified. | PartSelector, SetMultipartBodyString, SetMultipartBodyBd, SetMultipartBodyStream |
Choosing a Request Method
| Request Type | One-Call Method | Separate Send Method | Use When |
|---|---|---|---|
| No request body | FullRequestNoBody, FullRequestNoBodySb, FullRequestNoBodyBd | SendReqNoBody | GET, HEAD, DELETE, or any REST call where no request body is sent. |
| String body | FullRequestString | SendReqStringBody | Sending JSON, XML, text, or other string content. |
| StringBuilder body | FullRequestSb | SendReqSb | Sending text already held in a StringBuilder. |
| Binary byte array body | FullRequestBinary | SendReqBinaryBody | Sending binary request content from a byte array. |
| BinData body | FullRequestBd | SendReqBd | Sending binary data already held in a BinData object. |
| Stream body | FullRequestStream | SendReqStreamBody | Uploading from a file stream, memory stream, or other Stream source. |
| Form URL encoded body | FullRequestFormUrlEncoded | SendReqFormUrlEncoded | Sending application/x-www-form-urlencoded body content from the accumulated query parameters. |
| Multipart body | FullRequestMultipart | SendReqMultipart | Sending multipart/form-data or other multipart requests with one or more parts. |
FullRequest vs SendReq:
Use FullRequest* methods for simple one-call workflows.
Use SendReq* plus
ReadResponseHeader and response-body readers when the
application needs finer control over streaming, chunked reads, or response handling.
Request Headers, Query Parameters, and Path Parameters
| Need | Members | Guidance |
|---|---|---|
| Add or replace a request header | AddHeader | If the header already exists, it is replaced. |
| Remove a request header | RemoveHeader | Removes all headers matching the given name. |
| Clear all request headers | ClearAllHeaders | Resets the request-header collection. |
| Control folded headers | AllowHeaderFolding | Disable only for providers that require headers to remain on single unfolded lines. |
| Control Q/B encoding of non-ASCII headers | AllowHeaderQB | Enabled by default. Disable only if the server requires raw non-ASCII headers. |
| Add a query parameter | AddQueryParam | Replaces an existing parameter of the same name unless AllowDuplicateQueryParams is set in UncommonOptions. |
| Add many query parameters | AddQueryParams | Accepts a URL-encoded query string such as field1=value1&field2=value2. |
| Remove query parameters | RemoveQueryParam, ClearAllQueryParams | Removes selected query parameters or clears all query parameters. |
| Add path substitutions | AddPathParam | Replaces placeholders in URI paths before the request is sent. |
| Clear path substitutions | ClearAllPathParams | Removes all previously configured path parameters. |
Authentication Options
| Authentication Type | Members | Purpose |
|---|---|---|
| Manual Authorization Header | Authorization | Sets the value of the HTTP Authorization request header directly. |
| Basic Authentication | SetAuthBasic, SetAuthBasicSecure, EnableSecrets | Adds an Authorization: Basic ... header. Basic authentication should normally be used only with TLS. |
| OAuth2 Bearer Token | SetAuthOAuth2 | Adds Authorization: Bearer <access_token> using a populated OAuth2 object. |
| OAuth 1.0 / 1.0a | SetAuthOAuth1 | Adds OAuth 1.0 authentication either in query parameters or in the Authorization header. |
| AWS Request Signing | SetAuthAws | Automatically signs Amazon AWS REST requests using an AuthAws provider. |
| Azure Storage | SetAuthAzureStorage | Adds authorization for Azure Storage Service requests. |
| Azure SAS | SetAuthAzureSas | Adds Authorization: SharedAccessSignature ... for Azure SAS authentication. |
| Google APIs | SetAuthGoogle | Uses an AuthGoogle provider for Google API requests. |
| Amazon MWS | AddMwsSignature | Adds the Amazon Marketplace Web Service signature parameter after all request parameters have been added. |
| Clear Authentication | ClearAuth | Removes all authentication settings from the REST object. |
Security note:
Basic authentication sends username:password as
Base64 in the Authorization header. Chilkat normally disallows Basic authentication
over insecure connections unless the connection is TLS, SSH tunneled, localhost,
or AllowInsecureBasicAuth is explicitly set.
Multipart Request Support
Multipart requests are built by creating one or more parts, selecting a target part with PartSelector, and then setting headers and content for that part. An empty PartSelector targets the top-level header. A value such as 1 targets the first sub-part, and 1.2 targets the second sub-part inside the first part.
| Need | Members | Notes |
|---|---|---|
| Select the multipart part to modify | PartSelector | Use "" for the top-level header, 1 for the first sub-part, 2 for the second sub-part, etc. |
| Set text content | SetMultipartBodyString, SetMultipartBodySb | Sets text content for the selected multipart part. |
| Set binary content | SetMultipartBodyBinary, SetMultipartBodyBd | Sets byte-array or BinData content for the selected part. |
| Set stream content | SetMultipartBodyStream | Uses a Stream as the selected part’s body source. |
| Send the multipart request | FullRequestMultipart, SendReqMultipart | Choose the one-call or separate send/read model. |
| Reset multipart state | ClearAllParts | Clears sub-parts before preparing a new request. |
Response Handling
| Need | Members | Guidance |
|---|---|---|
| Read only the response header first | ReadResponseHeader | Returns the HTTP status code, or -1 if no response was received. |
| Read text response body | ReadRespBodyString, ReadRespSb | Use when the response body is known to be text, JSON, XML, or similar. |
| Read binary response body | ReadRespBodyBinary, ReadRespBd | Use for images, PDFs, ZIP files, and other binary response bodies. |
| Read response body to a stream | ReadRespBodyStream | Useful for large responses or streaming directly to a file or custom stream. |
| Read response body in chunks | ReadRespChunkBd | Returns 1 for another chunk, 0 for final bytes, and -1 for failure. |
| Stream FullRequest response body | SetResponseBodyStream, ClearResponseBodyStream | Streams the response body to a supplied stream when the status code matches the expected value or range. |
| Inspect response status | ResponseStatusCode, ResponseStatusText | Provides the status code and status text from the most recent response. |
| Inspect response headers | ResponseHeader, ResponseHdrByName, ResponseHdrName, ResponseHdrValue, NumResponseHeaders | Access the full response header, individual headers by name, or indexed header fields. |
| Track redirects | LastRedirectUrl | Contains the most recent Location header value when the response was a redirect. |
Connections, Timeouts, and Streaming
| Capability | Members | Purpose |
|---|---|---|
| Connect directly | Connect | Establishes the initial connection to a hostname and port, optionally using TLS. |
| Use an advanced connection | UseConnection | Uses an already-connected Socket, which can be TLS, plain TCP, proxied, SOCKS, or tunneled. |
| Close the REST connection | Disconnect | Closes the connection, or closes the logical channel when used through an SSH tunnel. |
| Connection timeout | ConnectTimeoutMs | Maximum time to wait for the server to accept the connection. |
| Idle timeout | IdleTimeoutMs | Maximum time to wait when incoming or outgoing data has stopped. This is not an overall request timeout. |
| Upload with Content-Length when possible | StreamNonChunked | When true, stream uploads use non-chunked transfer if the size is known. |
| Progress callbacks | PercentDoneOnSend, HeartbeatMs | Controls whether percent completion applies to upload progress or response download progress. |
Debugging and Diagnostics
Chilkat.Rest provides detailed request and response diagnostics. It can also compose a request without actually sending it, which is useful for verifying headers, query parameters, path substitutions, and body layout.
| Diagnostic Need | Use |
|---|---|
| Detailed information about the last operation | LastErrorText |
| Connection failure category | ConnectFailReason |
| View the last request start line | LastRequestStartLine |
| View the last request header | LastRequestHeader |
| View the response status code and text | ResponseStatusCode, ResponseStatusText |
| View the full response header | ResponseHeader |
| Compose request without sending | DebugMode, GetLastDebugRequest |
| Get structured details after selected calls | GetLastJsonData |
| Inspect redirect target | LastRedirectUrl |
Debug tip:
Set DebugMode = true to prevent a request from being
sent. Then call GetLastDebugRequest to inspect the
exact HTTP request that would have been transmitted.
Best Practices
| Recommendation | Reason |
|---|---|
| Pass only the hostname to Connect. | The connection target is the host and port. Full URLs belong outside Connect. |
| Pass only the URI path to request methods. | FullRequest* and SendReq* methods expect values such as /api/v1/items?limit=50, not a full URL. |
| Use FullRequest* methods for straightforward API calls. | They simplify common REST workflows by sending the request and reading the response in one call. |
| Use separate SendReq* and read methods for streaming or advanced response handling. | This gives the application control over when and how the response header and body are read. |
| Use provider-specific auth objects rather than manually building signatures. | SetAuthAws, SetAuthAzureStorage, SetAuthGoogle, and related methods centralize signing and authorization behavior. |
| Use EnableSecrets for Basic auth passwords when possible. | It allows credentials to be resolved from Windows Credential Manager or Apple Keychain instead of being embedded directly in code. |
| Use UseConnection for proxies, SOCKS, SSH tunnels, or custom TLS socket setup. | The Rest class keeps HTTP request logic separate from advanced socket-connection setup. |
| Clear request state between unrelated requests. | Use ClearAllHeaders, ClearAllQueryParams, ClearAllPathParams, and ClearAllParts to avoid carrying old state into the next request. |
| Use DebugMode before troubleshooting a live API. | It lets you verify the exact request without sending it. |
Summary
Chilkat.Rest is a flexible REST client for applications that need detailed control over request construction, authentication, connection reuse, multipart bodies, streaming, response parsing, and diagnostics. It is especially useful for APIs where the application must carefully manage headers, query parameters, provider-specific signing, request bodies, and low-level response handling.
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.