HTTP Client
CSML includes a native HTTP client. The following verbs are accepted:
- GET
- POST
- PUT
- PATCH
- DELETE
HTTP will automatically add the following headers to any request:
- Content-Type: application/json;
- Accept: application/json
In other words, HTTP requests only allow you to send and query json-formatted data.
Performing a HTTP request
To build your request, you can chain explicit methods to the HTTP function. No request is actually performed until
.send() is added, allowing you to gradually build your request.Here is a simple example:
1
do pet = HTTP("https://example.com/pets/1").get().send()
2
3
// or, if no verb is specified, .get() is implicitly used
4
do pet2 = HTTP("https://example.com/pets/2").send()
5
6
say "This pet is called: {{pet.name}}"
Copied!
You can also create more complex requests:
1
do req = HTTP("https://example.com/pets").set({"authorization":"Bearer XXXXX"})
2
3
if (query_mode == "retrieve") {
4
// retrieve all the available pets from the API
5
do req = req.get()
6
}
7
else {
8
// this will create a new pet
9
do req = req.post({"name": "Oreo", "breed": "poodle"})
10
}
11
12
do res = req.send()
13
14
say "{{res}}"
Copied!
The available methods are:
.get()/.post(body)/.put(body)/.patch(body)/.delete(): set the request verb, and add an optional JSON-formattedbody.set(data): set the request headers, where{"x-api-key":"somevalue"}is added asx-api-key:somevalueheaders.auth(username, password)set basic auth headers.query(data): set the query strings, where{"key":"value"}is automatically translated to?key=value.disable_ssl_verify(): for situations where you know that the endpoint comes with an invalid SSL certificate, you can disable SSL verification to bypass this protection. This option should only be used if you know what you are doing!
Analyzing the response
You can check whether the call returned a response by using the
.is_error() method on the response object.1
do res = HTTP("https://example.com/does-not-exist").send()
2
3
say res.is_error() // true
Copied!
The
.get_info() method lets you inspect the response of HTTP calls, even when the call returns an error (in which case .get_info() will also contain the body):1
do res = HTTP("https://example.com/does-not-exist").send()
2
3
say "{{res.get_info().headers}}" // the response headers
4
say "{{res.get_info().status}}" // 404
5
say "{{res.get_info().body}}" // only set in case of error
6
7
say "{{res}}" // the body in case of success, or Null in case of error
Copied!
.is_error() and .get_info() are very useful methods to correctly handle HTTP responses!1
// You can handle error cases like this:
2
if (res.is_error()) {
3
say "Hmmm... something happened"
4
5
// For example, you can differentiate between 4XX and 5XX errors
6
if (res.get_info().status >= 500) say "The server is not happy"
7
else if (res.get_info().status >= 400) say "Something is wrong on the client side"
8
}
Copied!
Last modified 15d ago
Export as PDF
Copy link
Edit on GitHub