Allows a server to make HTTP requests.
Memory Category | Instances |
---|
Type | Member | History | |
---|---|---|---|
bool | HttpEnabled | ||
string | GenerateGUID (bool wrapInCurlyBraces = true) | 138 170 | |
string | GetAsync (string url, bool nocache = false, Variant headers) | 128 251 250 251 | |
bool | GetHttpEnabled () | 351 350 351 | |
Secret | GetSecret (string key) | 596 | |
string | GetUserAgent () | 412 | |
Variant | JSONDecode (string input) | 130 555 554 557 | |
string | JSONEncode (Variant input) | 130 554 | |
string | PostAsync (string url, string data, HttpContentType content_type = ApplicationJson, bool compress = false, Variant headers) | 220 251 250 251 | |
Dictionary | RequestAsync (Dictionary requestOptions) | 343 | |
Instance | RequestInternal (Dictionary options) | 352 | |
null | SetHttpEnabled (bool enabled) | 351 350 351 573 | |
string | UrlEncode (string input) | 128 | |
57 members inherited from Instance |
Requests are made with the RequestAsync function. The GetAsync and PostAsync functions may also be used as shorthand for specific HTTP methods, but these are discouraged in favor of RequestAsync.
Each request function can receive custom headers to be included in the request. However, the following headers are locked, and cannot be included by the caller:
Header | Notes |
---|---|
Accept-Encoding |
|
Connection |
|
Content-Encoding |
Allowed by RequestAsync. |
Content-Length |
|
Content-Type |
Allowed by RequestAsync. |
Expect |
|
Forwarded |
|
Host |
|
Proxy-Connection |
|
User-Agent |
|
Via |
|
X-Att-Deviceid |
|
X-Forwarded-For |
|
X-Forwarded-Host |
|
X-Forwarded-Proto |
|
X-Wap-Profile |
Attempting to include a locked header causes the following error to be thrown:
Header "HEADER" is not allowed!
Where HEADER
is the name of the header.
By default, HttpService includes a number of headers along with each request:
Header | Value | Notes |
---|---|---|
Accept |
*/* |
|
Accept-Encoding |
gzip, deflate |
|
Cache-Control |
no-cache |
|
Content-Length |
(body length) | Length of the given body. Not included if the body is empty. |
Host |
(URL host) | Host part of the given URL. Not included if the URL has no host (e.g. an IP is used instead). |
Roblox-Id |
(place ID) | Corresponds to DataModel.PlaceId. |
User-Agent |
(user agent) | Depends on the current peer. |
Such headers that are not locked can be overridden. These headers are included
with every request, except for Content-Length
, which is included with all
methods except GET
and HEAD
. Certain request functions may include other
headers.
Requests are sent with a specific user agent that depends on the current peer:
Peer | User agent |
---|---|
Server | RobloxGameCloud/1.0 (+http://www.roblox.com) |
Studio | RobloxStudio/WinInet |
Header names are case-insensitive. If multiple equivalent headers are specified, only one is chosen (which header is chosen is undefined).
Only servers can make requests. If a request function is called on a client, the following error is thrown:
Http requests can only be executed by game server
The URL schemes allowed by HttpService are http
and https
. Domains are
filtered using a blacklist; requests to Roblox domains are disallowed, while
requests to any other domains are allowed. If a URL is disallowed or otherwise
invalid, then the following error will be thrown:
URL: Trust check failed
Where URL
is the given URL. Some request functions may throw a more specific
error instead.
Requests made by HttpService are rate-limited to 500 requests per minute. When a request is made after the limit is exceeded, the following error is thrown:
Number of requests exceeded limit
There is a limit to the number of concurrent requests that can be made by HttpService. When a request is made, it is put into a "slot", and remains there until the request is resolved. When all slots are occupied, new requests will block until a slot becomes available.
If a given URL is empty, then the following error will be thrown:
Empty URL
If the HTTP client encounters an error while making a request, then it will be thrown as the following:
HttpError: MESSAGE
Where MESSAGE
describes the error. For example, if the DNS server was unable
to resolve the given domain, the error will be HttpError: DnsResolve
.
Generates a Universally Unique Identifier (UUID).
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
wrapInCurlyBraces | bool | true |
Return Type | string |
---|
GenerateGUID returns a UUID version 4 string as defined by RFC 4122, which is generated pseudo-randomly.
If wrapInCurlyBraces is true, then the returned string will begin and end with
curly braces ({}
). If false, then the braces are omitted.
Sends a GET request to a website.
See the HttpService Details section for information regarding all request functions.
Parameters | 3 |
---|
Name | Type | Default |
---|---|---|
url | string | none |
nocache | bool | false |
headers | Variant | none |
Return Type | string |
---|---|
ScriptContext | Server |
GetAsync makes a request using the GET method. url is the URL to which the
request will be sent. If nocache is true, then the Cache-Control
header of
the request will be set to no-cache
. headers is an optional table of HTTP
headers.
If successful, GetAsync returns the body of the response.
headers is an optional table for specifying additional headers to be included with the request. Each entry must be a key-value pair, where the key is a string indicating a header name, and the value is a string indicating the header value.
If the response returns a non-successful status code, then the status is thrown as an error:
HTTP 000 (MESSAGE)
Where 000
is the status code, and MESSAGE
is the status message.
Cache-Control
is set to no-cache
regardless of the nocache argument.
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | bool |
---|---|
Security | RobloxScriptSecurity |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
key | string | none |
Return Type | Secret |
---|
Parameters | 0 |
---|
Name | Type | Default |
---|---|---|
No parameters. |
Return Type | string |
---|---|
Security | RobloxScriptSecurity |
Determines whether HttpService can make requests.
Value Type | bool |
---|---|
Security | LocalUserSecurity |
Category | Data |
Can Load | true |
Can Save | true |
If false, then GetAsync, PostAsync, and RequestAsync will throw the following error:
Http requests are not enabled. Enable via game settings
Decodes a JSON-formatted string into a value. The string is decoded according to RFC8259.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
input | string | none |
Return Type | Variant |
---|
The following JSON types are converted into a corresponding Lua type:
Encodes input into a JSON-formatted string. input cannot be nil.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
input | Variant | none |
Return Type | string |
---|
A boolean is mapped directly to a JSON boolean. A number is encoded as a JSON number. Infinity and NaN are encoded as a JSON null.
A string is encoded as a UTF-8 string. The following characters are escaped:
Character | Code | Escape |
---|---|---|
Backspace | 0x08 | \b |
Horzontal tab | 0x09 | \t |
Line feed | 0x0A | \n |
Form feed | 0x0C | \f |
Carriage Return | 0x0D | \r |
Double quote | 0x22 | \" |
Backslash | 0x5C | \\ |
Control characters (0x00 - 0x1F) not in this list are escaped as \u00XX
, where
XX
is the character code in hexadecimal.
Other unicode characters are encoded as-is. A malformed unicode character within any encoded string causes the following error to be thrown:
Can't convert to JSON
A table is encoded as either a JSON array or a JSON object, which depends on the content. A table is interpreted as an array if it is empty, or if it contains the integer 1 as a key. Otherwise, it is treated as an object.
Tables are encoded recursively. If a table that is being or has already been encoded is traversed, the following error is thrown:
tables cannot be cyclic
A table interpreted as an array encodes integer keys from 1 to the length of the table. Other keys are ignored, and are not traversed.
A table interpreted as an object encodes certain types of keys to JSON strings. Keys are encoded in the same way as string values. The method for encoding non-string keys is undefined. It is possible that such a key will be converted to a string, throw an error, or be ignored entirely.
Other types are encoded as a JSON null.
Sends a POST request to a website.
Parameters | 5 |
---|
Name | Type | Default |
---|---|---|
url | string | none |
data | string | none |
content_type | HttpContentType | ApplicationJson |
compress | bool | false |
headers | Variant | none |
Return Type | string |
---|---|
ScriptContext | Server |
PostAsync makes a request using the POST method. url is the URL to which the request will be sent, and data is the body of the request.
content_type optionally sets the Content-Type
header according to the given
HttpContentType value.
compress optionally determines whether the body will be compressed with gzip
encoding. The body will be sent compressed only if the compressed content is
shorter than the uncompressed content. If compressed, then the
Content-Encoding
header is set to gzip
.
headers is an optional table for specifying additional headers to be included with the request. Each entry must be a key-value pair, where the key is a string indicating a header name, and the value is a string indicating the header value.
If the response returns a non-successful status code, then the status is thrown as an error:
HTTP 000 (MESSAGE)
Where 000
is the status code, and MESSAGE
is the status message.
The length of data cannot be greater than or equal to 1024KB (maximum is 1,023,999 bytes). If data is too large, then the following error will be thrown:
Post data too large. Limit: 1024 KB. Post size: SIZE KB
Where SIZE
is the length of data in kilobytes. Note that RequestAsync
does not have this limit.
Sends an HTTP request and receives the response.
See the HttpService Details section for information regarding all request functions.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
requestOptions | Dictionary | none |
Return Type | Dictionary |
---|
requestOptions specifies the content of the request using the following fields:
Field | Type | Required | Description |
---|---|---|---|
Body |
string | no | The body of the request. |
Headers |
Dictionary | no | A table containing headers to send with the request. |
Method |
string | no | The HTTP request method to be used. Defaults to GET . |
Url |
string | yes | The URL to which the request will be sent. |
If Url
has a blacklisted Roblox domain, then the following error will be
thrown:
HttpService is not allowed to access ROBLOX resources
Method
, which is case-sensitive, must be one of GET
, HEAD
, POST
, PUT
,
DELETE
, TRACE
, OPTIONS
, CONNECT
, or PATCH
. If Method
is GET
or
HEAD
, and Body
is specified, then the following error will be thrown:
Invalid request options, Body should be empty for 'GET' or 'HEAD' method
RequestAsync blocks until a response has been received and processed, or the request has timed out.
Each entry to the Headers
table must be a key-value pair, where the key is a
string indicating a header name, and the value is a string indicating the header
value.
If successful, RequestAsync returns response data as a table with the following fields:
Field | Type | Description |
---|---|---|
Body |
string | The body of the response. |
Headers |
Dictionary | A table of response headers. |
StatusCode |
int | The HTTP status code of the response. |
StatusMessage |
string | A readable message corresponding to the StatusCode. |
Success |
bool | Whether or not the request succeeded. |
The response Headers field is a table, where each key is a string indicating a header name, and the value is a string indicating the header value. Header names, which are case-insensitive, are normalized to lowercase. If a header was sent multiple times, the value of the latest such header is selected.
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
options | Dictionary | none |
Return Type | Instance |
---|---|
Security | RobloxScriptSecurity |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
enabled | bool | none |
Return Type | null |
---|---|
Security | RobloxScriptSecurity |
Parameters | 1 |
---|
Name | Type | Default |
---|---|---|
input | string | none |
Return Type | string |
---|