Network.fetchText Action

Format

s = CS.Network.fetchText(url := ...
ʃ, method := ...ʅ
ʃ, headers := ...ʅ
ʃ, body := ...ʅʃ, bodyFormat := ...ʅ
ʃ, detailed := ...ʅ
ʃ, responseHeadersFormat := ...ʅ)

Argument	Description	Types / Required
url	The URL to fetch.	string required
method	The HTTP request method. The default value is is "GET".	string not required
headers	Request headers to send to the server.	array, object not required
body	The body to include with the request.	object, string not required
bodyFormat	The format of the body. The default value is "autodetect".	string not required
detailed	If true, the response status and headers are returned along with the body. The default value is false.	boolean not required
responseHeadersFormat	Indicates how response headers are returned. The default value is "object".	string not required

Description

The Network.fetchText action submits a HTTP request to a server and returns the response, with or without details, in text format.

This action is a wrapper around the actions Network.fetch and Network.fetchBody. The convenience methods include:

Network.fetchBytes: The response is returned as binary data.
Network.fetchFile: The response is saved to the disk.
Network.fetchJson: The response is parsed as JSON and returned as an array, object, etc.
Network.fetchText: The response is returned as text.

URL

The required argument, url, specifies the address of the server resource to access, such as a file or an API endpoint. The URL must contain valid characters. To convert dynamic text to a valid URL, use the encode function with the arguments URI or URIComponent.

Method

The optional argument, method, details the HTTP request method, with the argument defaulting to "GET". The possible options include:

Method	Option
"GET"	"The GET method requests a representation of the specified resource."
"POST"	"The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server." When using POST, you must specify a body.
"PUT"	"The PUT method replaces all current representations of the target resource with the request content."
"DELETE"	"The DELETE method deletes the specified resource."

Headers

You can include additional information in the request by specifying headers to send as part of the HTTP request. When specified as an array, or if an array element is a string, it is added as a fully defined header. If the headers are specified as an object, or if an array element is an object, that object's key/value pairs are combined to create a header with the object's key corresponding to a header name, and the object's value corresponding to a header value.

For example, the following headers, shown as a JSON array and object, are identical:

[
"Accept: application/json",
"Authorization: Bearer ACCESS_TOKEN"
]

{
"Accept": "application/json",
"Authorization": "Bearer ACCESS_TOKEN"
}

Body

If your request requires a payload, such as when using the POST method, the request body is specified using the argument body, with the format optionally specified using bodyFormat.

The body will be treated as JSON when:

bodyFormat is "json".
bodyFormat is undefined and:
- body is defined as an object;
- or the header has "Content-Type" set to "application/json".

For example, the body specified in these arguments would be treated as JSON:

{
"url": "https://...",
"body": {
"name": "CSPro Mailing List",
"email": "cspro@lists.census.gov"
}
}

If none of these JSON-related conditions applies, the body is converted from binary data specified using a string. If the body's MIME type is known (e.g., from a data URL), a "Content-Type" header with this type will be set if no such header exists. For example:

{
"url": "https://...",
"method": "POST",
"body": "Hello, World!",
"bodyFormat": "text"
}

Detailed Response

If the optional argument detailed is true, the action will no longer return just the body, but will instead return an object containing the response body, as well as details about the response. These details include:

Key	Value
"status"	A number indicating the HTTP status code of the response.
"ok"	A boolean flag indicating if the response was successful. Success is a status code in the range 200 - 299.
"headers"	An object, or array, based on the optional argument responseHeadersFormat, with the response headers. If returned as an object, which is the default setting, the header names and values are represented as the keys and values of the "headers" object. If returned as an array, the headers are returned as an array of strings. The response header format mirrors that of the request headers detailed above.
"body"	The response body that would be returned directly if detailed were not true.

Return Value

By default, the action returns a string with the HTTP response body as text. If detailed is true, the action returns an object with the response body as text and details about the response as described above.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form, or if:

There is an error submitting the HTTP request to the server or processing the response.
The response status code is not in the range 200 - 299. If you need to process a response with a status code not in this range, use the action Network.fetchBody.

Example (CSPro Logic)

errmsg("This is the readme for the CSPro open source repository:\n\n%s",
CS.Network.fetchText(url := "https://raw.githubusercontent.com/csprousers/cspro/refs/heads/dev/README.md"));

Example (JavaScript)

CS.Network.fetchTextAsync({
url: "https://raw.githubusercontent.com/csprousers/cspro/refs/heads/dev/cspro/zUtilO/Versioning.h"
})
.then(text => {
console.log("This is the current versioning information from " +
"the CSPro open source repository:\n\n" + text);
})
.catch(e => {
CS.UI.alertAsync({
text: e.message
});
});

See also: Network Action Invoker Namespace