Syncplify.me Server v8

Appearance

HttpRes response object ​

Every time you call an HttpCli verb method, it returns an HttpRes object containing the response data and metadata.

Example Usage ​

ts
var hc = new HttpCli();
var res = hc.Url("https://www.example.com").Timeout(30).Get();
// "res" is an HttpRes object with its own methods

The HttpRes object provides the following methods:

Ok ​

ts
res.Ok(): boolean;

Returns true if the HTTP/HTTPS call completed, or false otherwise (for example a DNS failure, a refused connection, a timeout or a rejected TLS certificate). Check this first, before reading anything else from the response.

Ok() and StatusCode() answer different questions. Ok() is false only when the request never completed at all, in which case StatusCode() is 0 and ErrorMsg() explains why. A 404 is a completed request, so Ok() is true and the status is 404. Check both.

IsValid ​

ts
res.IsValid(): boolean;

Identical to Ok(), kept for backward compatibility with existing scripts. Prefer Ok() in new code.

ErrorMsg ​

ts
res.ErrorMsg(): string;

Returns a human-readable explanation of why the call did not complete, or an empty string when it did.

StatusCode ​

ts
res.StatusCode(): number;

Returns the HTTP status code from the response (e.g., 200 for success, 201 for created, 403 for forbidden, 404 for not found, 500 for server error). See HTTP status codes for details.

BodyAsString ​

ts
res.BodyAsString(): string;

Returns the response body as a string (useful for web pages, JSON, etc.).

BodyAsBytes ​

ts
res.BodyAsBytes(): number[];

Returns the response body as an array of bytes (useful for binary data, such as images).

BodySaveToFile ​

ts
res.BodySaveToFile(filePath: string): boolean;

Saves the response body to the specified file path. Returns true if successful, false otherwise.

ContentType ​

ts
res.ContentType(): string;

Returns the MIME Content-Type reported by the server.

ContentLength ​

ts
res.ContentLength(): number;

Returns the Content-Length reported by the server (may be missing for some responses).

Encoding ​

ts
res.Encoding(): string[];

Returns the content transfer encodings reported by the server, as an array. It is empty for most responses.

Headers ​

ts
res.Headers(): object;

Returns a JSON object with all response headers as properties. Example:

json
{
  "Cache-Control": "max-age=604800",
  "Content-Type": "text/html; charset=UTF-8",
  "Date": "Sun, 30 Aug 2020 16:24:06 GMT",
  // ...
}

Cookies ​

ts
res.Cookies(): object[];

Returns an array of objects, each representing a cookie returned by the server. Example:

json
[
  {
    "Name": "1P_JAR",
    "Value": "2020-08-30-16",
    "Path": "/",
    "Domain": ".google.com",
    "Expires": "2020-09-29T16:32:11Z",
    // ...
  },
  // ...
]

TIP

Always check Ok() and StatusCode() before using the response data. Handle errors and unexpected status codes appropriately.

IMPORTANT

The body can only be read once. BodyAsString(), BodyAsBytes() and BodySaveToFile() each consume the response stream. The first call returns the content; every call after it returns an empty string, an empty array, or writes an empty file, with no error and no warning. Read it once into a variable and use that:

ts
// BROKEN: the log line is empty, because the body was already consumed
if (res.BodySaveToFile('/tmp/payload.json')) {
  Log(res.BodyAsString());
}

// Correct: read once, then use the value as often as you like
var body = res.BodyAsString();
Log(body);
WriteTextToFile('/tmp/payload.json', body);

Examples ​

Example 1: Log response body if successful ​

ts
var hc = new HttpCli();
var res = hc.Url("https://www.example.com").Timeout(30).Get();
if (res.Ok() && res.StatusCode() === 200) {
  Log(res.BodyAsString());
} else {
  Log('Request failed: ' + res.StatusCode());
}

Example 2: Save response body to file ​

ts
var hc = new HttpCli();
var res = hc.Url("https://www.example.com/image.png").Timeout(30).Get();
if (res.Ok() && res.StatusCode() === 200) {
  if (res.BodySaveToFile('/tmp/image.png')) {
    Log('Image saved successfully.');
  } else {
    Log('Failed to save image.');
  }
} else {
  Log('Request failed: ' + res.StatusCode());
}