# OAuthRequest

## Overview

`JSOAuthRequest` provides a streamlined way to create and execute OAuth requests within an application. It supports various HTTP verbs, such as GET, POST, PUT, DELETE, and PATCH, enabling flexible interactions with OAuth-enabled APIs. This wrapper simplifies the process of setting up requests by offering methods to add headers, parameters, and payloads.

Headers can be defined using `addHeader`, and body parameters can be specified with `addBodyParameter`. The `setPayload` function allows for setting the request's body payload, useful for scenarios involving larger data transmissions. For adding parameters, `addParameter` intelligently determines whether to place the parameter in the body or as a query string based on the HTTP verb. Additionally, `addQuerystringParameter` explicitly manages query string additions.

The class also supports OAuth-specific parameters like `scope` and others prefixed with `oauth_` through the `addOAuthParameter` method. The `execute` method runs the configured request and returns an `OAuthResponse` object containing details such as HTTP status codes and the response body.

## Methods Summarized

| Type                                                                                                   | Name                                                                      | Summary                                                                    |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| void                                                                                                   | [addBodyParameter(key, value)](#addbodyparameter-key-value)               | Add a body parameter to the request.                                       |
| void                                                                                                   | [addHeader(header, value)](#addheader-header-value)                       | Allows setting a header on the request object.                             |
| void                                                                                                   | [addOAuthParameter(key, value)](#addoauthparameter-key-value)             | Add an OAuth parameter, like 'scope', 'realm' or with the 'oauth\_' prefix |
| void                                                                                                   | [addParameter(key, value)](#addparameter-key-value)                       | Add a body or a query string parameter, depending on the request type.     |
| void                                                                                                   | [addQuerystringParameter(key, value)](#addquerystringparameter-key-value) | Add a query string parameter.                                              |
| [OAuthResponse](https://docs.servoy.com/reference/servoyextensions/server-plugins/oauth/oauthresponse) | [execute()](#execute)                                                     | Execute a request that was created with the OAuth service.                 |
| void                                                                                                   | [setPayload(data)](#setpayload-data)                                      | Set body payload.                                                          |

## Methods Detailed

### addBodyParameter(key, value)

Add a body parameter to the request.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the parameter name
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the parameter value

**Returns:** void

**Sample**

```js
var postRequest = service.createPostRequest("https://.....");
postRequest.addBodyParameter("param1", "value1");
```

### addHeader(header, value)

Allows setting a header on the request object.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **header** the header name
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the header value

**Returns:** void

**Sample**

```js
var getRequest = service.createGetRequest("https://api.linkedin.com/v2/me");
getRequest.addHeader("Accept", "application/json");
```

### addOAuthParameter(key, value)

Add an OAuth parameter, like 'scope', 'realm' or with the 'oauth\_' prefix

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** one of 'scope', 'realm' or starting with 'oauth\_'
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the oauth parameter value

**Returns:** void

### addParameter(key, value)

Add a body or a query string parameter, depending on the request type.\
If the request allows a body (POST, PUT, DELETE, PATCH) then it adds it as a body parameter.\
Otherwise it is added as a query string parameter.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the parameter name
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the parameter value

**Returns:** void

### addQuerystringParameter(key, value)

Add a query string parameter.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **key** the query string parameter name
* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **value** the parameter value

**Returns:** void

### execute()

Execute a request that was created with the OAuth service.

**Returns:** [OAuthResponse](https://docs.servoy.com/reference/servoyextensions/server-plugins/oauth/oauthresponse) the OAuthResponse object

**Sample**

```js
var request = service.createRequest(plugins.oauth.RequestType.GET, "https://api.linkedin.com/v2/me");
request.addHeader("Accept", "application/json");

var response = request.execute();
if (response.getCode() == 200) {
		var json = response.getAsJSON();
		application.output("Name is "+json.firstName);
	}
else
{
		application.output("ERROR http status "+response.getCode());
		application.output(response.getBody())
}
```

### setPayload(data)

Set body payload.

**Parameters**

* [String](https://docs.servoy.com/reference/servoycore/dev-api/js-lib/string) **data** ;

**Returns:** void

**Sample**

```js
var putRequest = service.createPutRequest("https://graph.microsoft.com/v1.0/me/drive/root:/FolderAA/FileBB.txt:/content");
putRequest.addHeader("Content-Type", "text/plain");
putRequest.setPayload("ABC");
```

***