s = CS.Network.fetchJson(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 |
The
Network.fetchJson action submits a HTTP request to a server and returns the response, with or without details, in
JSON format.
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.
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." |
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"
}
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"
}
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. |
By default, the action returns the HTTP response body parsed as JSON, returning a string, number, boolean, array, or object. If
detailed is
true, the action returns an object with the response body as parsed JSON and details about the response as described above.
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.
- The response is not valid JSON.
// display information about the latest few CSPro releases;
// the GitHub API requires the specification of a User-Agent header
CS.Network.fetchJsonAsync({
url: "https://api.github.com/repos/csprousers/cspro/releases?per_page=5",
headers: [
"User-Agent: CSPro Help Documentation Example"
]
})
.then(releases => {
// the releases endpoint returns an array of objects
releases.forEach(release => {
console.log(
`Release tagged '${release.tag_name}' ` +
`authored by '${release.author.login}' ` +
`created at '${release.created_at}'`
);
});
})
.catch(e => {
CS.UI.alertAsync({
text: e.message
});
});