# HttpService

HttpService : `Instance`

## Overview

Provides HTTP request feature used to communicate with external web services. With this feature, a variety of features such as analytics system integration, cloud-based data processing, external server environment application, or real-time data transfer can be integrated into game world.

In addition, when communicating with API in JSON format, data can easily be serialized or deserialized with the JSONEncode and JSONDecode methods.

It is recommended to send HTTP requests only to trusted and secure external platforms in order to maintain a stable and safe world environment.

## Properties

### HttpEnabled

`bool`

A setting used to allow communication with external web services through HttpService.

If this value is set true, HTTP requests can be sent to external servers in script using the GetAsync, PostAsync, and RequestAsync methods.

This option can also be enabled in the studio’s Game Settings menu.

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

print(HttpService.HttpEnabled)
```

## Methods

### GenerateGUID

It generates an UUID string only once in the entire execution environment; any subsequent calls return the same UUID.

The generated identifier expresses 16-byte data into 32 hexadecimal characters, makes them in the form of 8-4-4-4-12, and provides them in a 36-character string (123e4567-e89b-12d3-a456-426655440000 for example).

#### Parameters

| `bool` bInWrapInCurlyBraces | Whether or not to include the curly brackets enclosing a string (default: false). |
| --------------------------- | --------------------------------------------------------------------------------- |

#### Return

| `string` | The generated UUID. |
| -------- | ------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local Result = HttpService:GenerateGUID(false)

print(Result)
```

### GetAsync

A simple way to transfer an HTTP GET request, it behaves similarly to RequestAsync, but it sends requested information as individual factor and returns only the body of response data.

If the value of NoCache is set true, it transfers a new request to server every time instead of using the cache of requests sent to the same address in the past.

#### Parameters

| `string` InUrl    | The URL of a web server to send request.               |
| ----------------- | ------------------------------------------------------ |
| `bool` InNoCache  | Whether or not to use cache (default: false).          |
| `Value` InHeaders | The header information to be included in HTTP request. |

#### Return

| `string` | The data returned by server in response to GET request. |
| -------- | ------------------------------------------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local baseUrl = "Enter the HTTP URL here"

local success, errorMessageOrResult, response = nil, nil, nil

success, errorMessageOrResult = pcall(function()
    response = HttpService:GetAsync(baseUrl)
end)

print("Success : ", success)
print("ErrorMessageOrResult : ", errorMessageOrResult)
print("Response : ", response)
```

### JSONDecode

Converts objects or arrays in JSON into a Lua table.

The JSON object is a table based on string keys; the JSON array is converted into an array of number keys starting from 1.

All numbers are interpreted as a float value and nesting structures are converted into recursive structures.

An empty JSON object or array is returned as an empty table.

#### Parameters

| `string` InInput | The JSON data to be converted. |
| ---------------- | ------------------------------ |

#### Return

| `Value` | The converted Lua table data. |
| ------- | ----------------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local data = HttpService:JSONDecode(jsonData)
print(data)
```

### JSONEncode

Converts Lua table into JSON object or array.

The value nil is not included in JSON; special numbers such as inf and nan are converted as well, but because they are not JSON standard, there may be a compatibility issue when integrating external systems.

An empty table is converted into an empty JSON array and if there is a circular reference in a table, an error occurs during conversion.

#### Parameters

| `Value` InInput | The Lua table data to be converted. |
| --------------- | ----------------------------------- |

#### Return

| `string` | The data in converted JSON. |
| -------- | --------------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local data = 
{
    ["message"] = "Hello OVERDARE!",
    ["data"] = 10,
}
local jsonData = HttpService:JSONEncode(data)
```

### PostAsync

Performs HTTP POST requests. It provides features similar to those of the RequestAsync() function, but it can transfer requested data in individual variable instead of a single dictionary and returns only the body instead of the entire response.

It is often used for light coding. It is better to use the RequestAsync() function instead in most situations.

In addition, if the compress option is set true, the body of a large request is automatically compressed in gzip for more efficient transfer.

#### Parameters

| `string` InUrl                       | The URL of a web server to send request.                                                                   |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `string` InData                      | The data to be transferred.                                                                                |
| `Enum.HttpContentType` InContentType | Transfer format (default: ApplicationJson) can be specified by adjusting the header value of Content Type. |
| `bool` InCompress                    | Whether or not to compress data in gzip when transferring data to server (default: false).                 |
| `Value` InHeaders                    | The header information to be included in HTTP request.                                                     |

#### Return

| `string` | The response data for POST request returned by server. |
| -------- | ------------------------------------------------------ |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")
local baseUrl = "Enter the HTTP URL here"

local success, errorMessageOrResult, response = nil, nil, nil

success, errorMessageOrResult = pcall(function()
    local data = 
    {
        ["message"] = "Hello OVERDARE!",
        ["data"] = 10,
    }
    local jsonData = HttpService:JSONEncode(data)

    local contentType = Enum.HttpContentType.ApplicationJson
    local compress = false
    local headers = {}
    response = HttpService:PostAsync(baseUrl, jsonData, contentType, compress, headers)
end)

print("Success : ", success)
print("ErrorMessageOrResult : ", errorMessageOrResult)
print("Response : ", response)
```

### RequestAsync

Sends an HTTP request using any method with the provided dictionary of information.

#### Parameters

| `Dictionary` InRequestOptions |   |
| ----------------------------- | - |

#### Return

| `Value` |   |
| ------- | - |

#### Code Samples

### UrlEncode

입력된 문자열 내의 예약 문자를 % 기호와 두 자리 16진수 코드로 변환하여, URL에서 안전하게 사용할 수 있는 퍼센트 인코딩(percent-encoding) 문자열을 생성합니다.

#### Parameters

| `string` InInput | The string (address) to be converted. |
| ---------------- | ------------------------------------- |

#### Return

| `string` | The converted string (address). |
| -------- | ------------------------------- |

#### Code Samples

```lua
local HttpService = game:GetService("HttpService")

local Query = "Hello #OVERDARE#"
local Encoded = HttpService:UrlEncode(Query)

print(Encoded)
```

## Events

## See also

{% content-ref url="../../../manual/script-manual/events-and-communication/json-and-http" %}
[json-and-http](https://docs.overdare.com/manual/script-manual/events-and-communication/json-and-http)
{% endcontent-ref %}