# JavaScript HTTP client library for a Plugin

### Remarks

The PATCH, POST, & PUT requests allow `data` to be supplied as either a string, byte array, or JavaScript object. For JavaScript Object data, unless the 'content-type' header is explicitly set, it will be understood as JSON Content & will automatically set the 'content-type' to 'application/json'. If the JavaScript Object data is Form URL Encoded Content you will need to explicitly set the 'content-type' header to 'application/x-www-form-urlencoded'

### Example

```javascript
plugin.Name="HTTPExample";

plugin.OnChangeRequest= onChangeRequest;

plugin.OnConnect= onConnect;

plugin.OnDisconnect= onDisconnect;

plugin.OnPoll= onPoll;

plugin.OnSynchronizeDevices= onSynchronizeDevices;

plugin.PollingInterval=1000;

var http =newHTTPClient();

function onChangeRequest(device, attribute, value){
    if(device.Id=="1"){
        switch(value){
            case"On":
                http.get("https://maker.ifttt.com/trigger/LivingLightsOn/with/key/abcdefg");
                break;
            case"Off":
                http.get("https://maker.ifttt.com/trigger/LivingLightsOff/with/key/abcdefg");
                break;
            default:
                break;
        }
    }
    else{
        throw"Commands for this device Id have not been implemented";
    }
}

function onConnect(){}

function onDisconnect(){}

function onPoll(){}

function onSynchronizeDevices(){
    var switch1 =newDevice();
    switch1.Id="1";
    switch1.DisplayName="Switch 1";
    switch1.Capabilities=["Switch"];
    switch1.Attributes=[];
    plugin.Devices[switch1.Id]= switch1;
}
```

## Methods

### get

Send a GET request to the specified URL.

```javascript
get(url, [options])
```
- `url` : Relative or absolute URL for the request.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### delete

Send a DELETE request to the specified URL.

```javascript
delete(url, [options])
```
- `url` : Relative or absolute URL for the request.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### head

Send a HEAD request to the specified URL.

```javascript
head(url, [options])
```
- `url` : Relative or absolute URL for the request.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### options

Send a OPTIONS request to the specified URL.

```javascript
options(url, [options])
```
- `url` : Relative or absolute URL for the request.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### post

Send a POST request to the specified URL.

```javascript
post(url, data, [options])
```
- `url` : Relative or absolute URL for the request.
- `data` : The HTTP Content sent to the server. Can be a string, Object, or byte array.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### put

Send a PUT request to the specified URL.

```javascript
put(url, data, [options])
```
- `url` : Relative or absolute URL for the request.
- `data` : The HTTP Content sent to the server. Can be a string, Object, or byte array.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

### patch

Send a PATCH request to the specified URL.

```javascript
patch(url, data, [options])
```
- `url` : Relative or absolute URL for the request.
- `data` : The HTTP Content sent to the server. Can be a string, Object, or byte array.
- `options`
  - `baseURL` : Will be prepended to `url` unless `url` is absolute.
  - `headers` : An object containing the HTTP request headers.
  - `auth` : Authentication credentials for the request.
  - `responseType` : The type of data returned by the request: 'arraybuffer', 'json', 'text', 'xml'. (default: 'json')
  - `followRedirects` : Boolean that indicates whether it will follow redirection responses. (default: true)
  - `timeout` : Time, in milliseconds, to wait before timing out. The default is 0 which waits indefinitely.

Returns an [HTTP Response Object](/content/docs/httpclient/#response-object/index.html)

## Response Object

All HTTP requests return a response object with the following properties:

| Property | Description |
| --- | --- |
| `data` | The response content. Will either be a string, JSON object, or XML object. |
| `status` | A integer representing the status code returned from the server |
| `statusText` | A string representing the status description returned from the server |
| `headers` | An object containing HTTP response headers. |

## Auth Object

| Property | Description |
| --- | --- |
| `username` | The username for the HTTP request. |
| `password` | The password for the HTTP request. |
| `authType` | The type of authentication used: 'auto', 'basic', 'digest'. (default: 'auto') |