# http.get

Retrieves data from an HTTP source.

```javascript
var response = await http.get(url, query, requestOptions);

// or with Promises:
http.get(url, query)
    .then(function(response) {
        ...
    });
```

# Input

| Variable | Required | Description |
|----------|----------|-------------|
| `url`    | yes      | The URL to retrieve. |
| `query`  | optional | *(object)* Optional URL query string parameters. Can be appended to the URL or passed as an object. |
| `requestOptions` | optional | *(object)* Additional request options such as custom headers. See **Request HTTP Headers** below. |

# Output

This function returns a Promise with the following data:

| Variable | Type | Description |
|----------|------|-------------|
| `success` | boolean | True if the command completed successfully. |
| `error`  | string | Error message if the command failed. |
| `statusCode` | number | *(On success)* The HTTP status code. |
| `headers` | array | *(On success)* Array containing the HTTP headers. |
| `body`   | string | *(On success)* The body of the reply as a string. |

# Request HTTP Headers

You can set HTTP headers using the `requestOptions` object.  
Currently, headers are the only supported option.

```javascript
var response = await http.get(
  "http://ptsv3.com/smartbots-playground",
  { param1: 1, param2: 2 },
  {
    "headers": {
       "x-my-header-1": "value-1",
       // ...
    }
  }
);
```

# Comments

This function performs an HTTP **GET** request to the specified URL.  
Query parameters can be either:

* appended directly to the URL, e.g. `example.com/?param1=1&param2=2`, or
* passed as an object, e.g. `{ param1: 1, param2: 2 }`

# Limitations

The playground responds with HTTP statusCode **206** when the response is too large. The returned response is trimmed to approximately 7168 bytes.

# Examples

```javascript
console.log("Doing http request...");

const response = await http.get("https://mysmartbots.com");
console.log("http result:", response.body);

// Gracefully stop the test script
exit();    
```

Or the same with Promises:

```javascript

console.log("Doing http request...");

http.get("https://mysmartbots.com")
    .then(function(response) {
        console.log("http result:", response.body);
    })
    .then(function() {
        // Gracefully stop the test script
        exit();
    });
```

A more advanced example with error handling:

```javascript
console.log("Doing http request...");

http.get("https://mysmartbots.com")
    .then(function(result) {
        if (!result.success) {
            // On error display the error message and stop the processing
            console.log("HTTP error:", result.error);
            throw "";
        }

        console.log("http result:", result.body);
    })
    .catch(function(err) {
        // This block allows cancelling the processing chain with throw ""
        if (err != "") { throw err; }
    })
    .then(function() {
        // Gracefully stop the test script
        exit();
    });
```