HTTP

Scripts reach the outside world over HTTP. An object can call any web server, and can also act as a small web server itself with a temporary URL. Part of the Communications feature.

Concepts

llHTTPRequest sends a request and returns a key; the answer arrives in http_response with the status, metadata and body
- Parameters set the method, content type, custom headers and certificate checks
- The response body is cut to 2048 bytes by default; HTTP_BODY_MAXLENGTH raises it to 16384 in Mono
- Requests are throttled per object; a throttled request returns NULL_KEY
- Escape values put into a URL
An object can serve HTTP
- Request a URL (or a secure one); the URL arrives in http_request with the method URL_REQUEST_GRANTED
- Each incoming request also arrives in http_request; read its headers and answer with llHTTPResponse within 25 seconds
- llSetContentType sets the type of the response, such as CONTENT_TYPE_JSON
- URLs are a limited resource: count the free ones and release those no longer needed
- URLs persist across state changes, but are lost when the object changes region or the region restarts; request a new one on CHANGED_REGION, CHANGED_REGION_START and on_rez
Objects can call each other’s URLs, which is the usual way to talk across regions
Send structured data as JSON

Functions and events

`key`	`llHTTPRequest(string url, list parameters, string body)`
`event`	`http_response(key request_id, integer status, list metadata, string body)`
`key`	`llRequestURL()`
`event`	`http_request(key request_id, string method, string body)`
	`llHTTPResponse(key request_id, integer status, string body)`

Scripting Details

Requests

`key`	`llHTTPRequest(string url, list parameters, string body)` Sends an HTTP request to the specified url containing body and configured via parameters. Raises an http_response event and returns a key query handle identifying the request.
`event`	`http_response(key request_id, integer status, list metadata, string body)` Triggered when an HTTP response body is received for a pending request_id, or if the request fails or times out.
`string`	`llEscapeURL(string url)` Returns a string representing the escaped/encoded version of url, replacing spaces with '%20' and non-alphanumeric characters with their '%xx' hexadecimal UTF-8 equivalent.
`string`	`llUnescapeURL(string url)` Returns a string representing the unescaped/decoded version of url, replacing '%20' with spaces and decoding raw UTF-8 characters.

Serving

`key`	`llRequestURL()` Asynchronously requests one HTTP URL for use by this script, triggering an http_request event. Returns a key query handle.
`key`	`llRequestSecureURL()` Asynchronously requests one secure HTTPS (SSL, port 12043) URL for use by this object, triggering an http_request event. Returns a key query handle.
	`llReleaseURL(string url)` Releases the specified url (previously obtained via llRequestURL), rendering it no longer usable.
`event`	`http_request(key request_id, string method, string body)` Triggered when the script's registered URL receives an incoming HTTP request identified by request_id.
	`llHTTPResponse(key request_id, integer status, string body)` Responds to the incoming HTTP request identified by request_id with the HTTP status code status and the payload body.
`string`	`llGetHTTPHeader(key request_id, string header)` Returns a string representing the value of the specified header associated with the HTTP request_id.
	`llSetContentType(key request_id, integer content_type)` Sets the 'Content-Type' header of subsequent HTTP server responses (via llHTTPResponse) for request_id using the specified content_type (a CONTENT_TYPE_* constant).
`integer`	`llGetFreeURLs()` Returns an integer representing the number of available HTTP URLs (remaining for the owner if the object is attached, or for the region if unattached).

Example

An object that answers web requests with its region name.

default
{
    state_entry()
    {
        llRequestURL();
    }

    on_rez(integer start_param)
    {
        llResetScript();
    }

    changed(integer change)
    {
        if (change & (CHANGED_REGION | CHANGED_REGION_START)) llResetScript();
    }

    http_request(key id, string method, string body)
    {
        if (method == URL_REQUEST_GRANTED)
            llOwnerSay("URL: " + body);
        else if (method == "GET")
            llHTTPResponse(id, 200, llGetRegionName());
        else
            llHTTPResponse(id, 405, "Method not allowed");
    }
}

Constant groups

Constant groups HTTPRequestParam 10 HTTPContentType 9 HTTPResponseError 1

See also Feature Communications Category Web SL Wiki LSL HTTP SL Wiki HTTP Server URL Registration Feature Data TransmissionPlanned Guide: an object as a web server