# Network

Fetching web data and images with HTTP

[Reference](index.md)

<a id="section-HTTP"></a>

## HTTP

<a id="http"></a>

### http

Use `http.request` to fetch data without stopping drawing. Start a request in
`setup()` or in response to an action, rather than on every frame. Store its
result in the callback and draw that state in `draw()`. A response can arrive
later or fail, so show a loading state and handle both outcomes.

```lua
function setup()
    message = "Loading…"
    http.request("https://codea.io", function(data, status, headers)
        if status >= 200 and status < 300 then
            message = "Received response: " .. status
        else
            message = "Server returned " .. status
        end
    end, function(errorMessage)
        message = "Request failed: " .. errorMessage
    end)
end

function draw()
    background(30)
    fill(255)
    text(message, WIDTH / 2, HEIGHT / 2)
end
```

<a id="http.request"></a>

### http.request(url, success, failure, options)

```lua
http.request(url, success, failure, options)
```

Starts an asynchronous HTTP request. `success(data, status, headers)` receives
a string for ordinary response bodies, or an `image` when the body decodes
as an image. `status` is the numeric HTTP status; `headers` is a table.
HTTP errors such as 404 still call `success`: check the status yourself.

`failure(message, response, status)` handles transport errors. The first
argument is a string; additional response data may be unavailable. Always
supply a failure callback when providing options.

Options are `method` (default `"GET"`), `headers` (string keys and values),
`data` (request body string), and `useragent` (User-Agent string).
For JSON, encode the body with `json.encode` and set the Content-Type header
to `application/json`. Decode string responses with `json.decode` and
handle its error return.

request a URL asynchronously

#### Parameters

- **url** (string): Absolute URL to request, normally using HTTPS.
- **success** (function): Callback receiving body, HTTP status, and response headers.
- **failure** (function, optional): Optional callback receiving the error message and available response details.
- **options** (table, optional): Optional request method, headers, body, and user agent.