Configuration methods

Before calling any HTTP/HTTPS verb to make the HttpCli perform a request, you must first create and configure the object according to your needs. This includes specifying the URL, request body, headers, timeout, and any authentication or other options required for your call.

The HttpCli object is highly flexible. For example, you might create and configure it as follows:

// Create HttpCli object
var hc = new HttpCli();
// Configure the hc object as needed...

Below are the available configuration methods:

Url

hc.Url(fullyQualifiedUrl: string): HttpCli;

Required. Sets the full URL for the HTTP/HTTPS request. Only the most recent call to .Url() is used.

Accept

hc.Accept(contentType: string): HttpCli;

Sets the expected MIME type for the server response. Only the most recent call to .Accept() is used.

ApiKey

hc.ApiKey(yourApiKey: string): HttpCli;

Sends the given string as Authorization: Basic <yourApiKey>, verbatim. Only the most recent call to .ApiKey() is used.

WARNING

Despite the name, this does not base64-encode anything, does not add an X-API-Key header and does not append the key to the URL. Most APIs do not expect what it sends. Use .Bearer() for a bearer token, or .Header() for a header-based key such as hc.Header("X-API-Key", key), and reach for .ApiKey() only when you have confirmed the server wants exactly an Authorization: Basic header containing your raw key.

BasicAuth

hc.BasicAuth(username: string, password: string): HttpCli;

Sets HTTP Basic Authentication credentials. Only the most recent call to .BasicAuth() is used.

Bearer

hc.Bearer(bearerToken: string): HttpCli;

Sets a Bearer Token for authentication. Only the most recent call to .Bearer() is used.

FormField

hc.FormField(fieldName: string, fieldValue: string): HttpCli;

Adds a form field to a multipart/form-data request body (typically for POST requests). This method is additive—call it multiple times to add multiple fields.

Header

hc.Header(headerName: string, headerValue: string): HttpCli;

Adds a custom header to the request. This method is additive—call it multiple times to add multiple headers.

InsecureSkipVerify

hc.InsecureSkipVerify(): HttpCli;

Accepts any server certificate, including self-signed certificates, when making HTTPS requests. Use with caution.

ReqBody

hc.ReqBody(body: string): HttpCli;

Sets the request body. The string is sent exactly as supplied: the bytes you pass are the bytes on the wire, with no re-encoding, no re-ordering and no wrapper. Only the most recent call to .ReqBody() is used.

The Content-Type is chosen as follows:

Situation	Content-Type sent
You set one with .Header("Content-Type", ...)	Yours, exactly. Header names are matched case-insensitively
You did not, and the body parses as JSON	application/json; charset=utf-8
You did not, and it does not	text/plain; charset=utf-8

// Sent verbatim, as application/json
hc.Url(endpoint).ReqBody(JSON.stringify({ name: "John", age: 42, tags: ["a"] })).Post();

// An explicit content type always wins
hc.Url(endpoint).Header("Content-Type", "application/xml").ReqBody(xml).Post();

IMPORTANT

Earlier builds of the SyncJS engine mangled most bodies. Only a flat JSON object whose values were all strings went out as JSON, and even that was re-serialised, which re-ordered its keys alphabetically. Everything else, including any JSON containing a number, a boolean, an array or a nested object, and any plain text, was sent as application/octet-stream with a binary prefix in front of it; an explicit Content-Type header was overwritten. All of that is fixed.

NOTE

.ReqBody() and .FormField() build two different request bodies and cannot both apply. When both are set, the form fields win, the request body is ignored, and a warning is written to the log.

Timeout

hc.Timeout(seconds: number): HttpCli;

Sets the request timeout in seconds. Only the most recent call to .Timeout() is used.

UserAgent

hc.UserAgent(softwareId: string): HttpCli;

Sets a custom User-Agent header. Only the most recent call to .UserAgent() is used.

NOTE

For methods that are additive (such as .FormField() and .Header()), each call adds a new value. For all others, only the most recent value is used.