Network utilities

GreyCat offers some network utilities to communicate with the outside world.
They are all located in the io package, so you need to add the use io; directive to access these functions.

HTTP

APIs are common ways to interact between different system. GreyCat provides means to perform GET, POST and PUT requests. All functions give offer the possibility to specify headers.

GET

Http::get requires the http endpoint as first parameter in form of a String, second parameter (nullable) is an array of HttpHeader. This second parameter can come handy when one need to specify a token_bearer or content-type for instance.
The body of the response is returned in the result of the function call.

fn call() {
    var googlePage = Http::get("http://www.google.com", null);
    var myData = Http::get("http://myEndpoint.lu", [HttpHeader{name: "Accept", value: "application/json"}, HttpHeader{name: "Bearer", value: "${myToken}"}]);
}

GetFile

Http::getFile is very similar to Http::get, but rather writes the body of the response into a File instead of returning the content in a string. There is therefore an additional parameter to specify the path of the file you want the result to be written.

fn call() {
    var filePath = "./data/file-${time::now().to(DurationUnit::milliseconds)}.json";
    Http::getFile("https://myDomain.com", filePath, null);
    var content = JsonReader { path:filePath };
    [...]
}

POST & PUT

Http::post and Http::put have similar parameters. The first parameter is the endpoint (String), the second is the content to be sent in the body of the request, and finally the list of headers, if any.
The data is encoded in JSON. The example shows how a Http:post request is made with params, a content, and a return value parsed as JSON from the String.

fn call() {
    var endpoint = "${base_endpoint}/datafetch?api_key=${this.api_key}&user_id=${this.user_id}";
    var request = {
        sampling: ["live"],
        structure_uuids: [structureUuid]
    };
    var result = Http::post(endpoint, request, this.defaultHeaders());
    var parsedResult = JsonReader::parse(result as String);
    [...]
}

When using Http::post to issue HTTP requests to GreyCat endpoints (when communicating to a different GreyCat server, or for testing):

• if the GreyCat endpoint is simply exposed (@expose), then the request should be an Array, var request = [ 123 ];, where the array elements match the endpoint parameters
• if in addition, the GreyCat endpoint is also decorated as @json_direct_param, then the endpoint must take a single parameter
• the Http::post will parse the result for you and create a GreyCat value. No need to call JsonReader::parse.

SMTP

Sending an email is possible, using the Smtp type.

SMTP Connection

You need to create an Smtp object that will specify the details of the server you target.
Once done with the configuration, you can call send with the email content you want to transmit.

fn call() {
    var smtpServer = Smtp{
        host: "smtp.mycompany.com",
        port: 587,
        mode: SmtpMode::starttls,
        authenticate: SmtpAuth::login,
        user: "it_s_me",
        pass: "my_pass"
    };
}

Email

The Email object allows to specify the various fields of the email. Recipients, subject, content, etc.

var myEmail = Email{
    from: "\"John DOE\" <john.doe@mycompany.com>",
    to: ["\"John BOSS\" <john.boss@mycompany.com>"],
    cc: [
        "\"John LEFTBUDDY\" <john.leftbuddy@mycompany.com>",
        "\"John RIGHTBUDDY\" <john.rightbuddy@mycompany.com>",
    ],
    bcc: null,
    body_is_html: false, //Text only
    subject: "Important things",
    body: "This is a text content.\n\nBest regards\nJohn",
};

This email can then be sent using

smtpServer.send(myEmail);

URL

It is sometimes necessary to extract parts of URLs. This utility type helps parsing and producing URLs.

var theUrl = Url::parse("https://www.mycompany.com/this/is/path?p1=true&p2=4#section");
println(theUrl);

Produces

{
  "_type": "io.Url",
  "protocol": "https",
  "host": "www.mycompany.com",
  "path": "/this/is/path",
  "params": { "p1": "true", "p2": "4" },
  "hash": "#section"
}