Introduction to the Unity web request APIs

Understand the main uses and architecture of Unity's web request APIs.

Read time 2 minutes

Last updated 7 days ago

UnityWebRequest

is Unity's HTTP/HTTPS networking API for communicating with web services, transferring files, and streaming data at runtime.

Common uses for the Unity web request system include:

Downloading content at runtime, such as:
- AssetBundles from remote servers, when using the regular AssetBundle or Addressables systems.
- Text/JSON for config, localization, and live tuning.
- Images (as Textures) and audio (as AudioClips) for dynamic content.
- Build-time or runtime patching via remote manifests.
Uploading data to servers, such as:
- Player metrics.
- Saved game state.
- Error/exception logs and crash reports.
- Custom telemetry and analytics.
Integrating with content delivery networks, authentication and security, payment platforms, multiplayer services, diagnostics, and remote build pipelines.
Implementing low-traffic, networked multiplayer and turn-based games, such as chess.

Architecture

The Unity web request system consists of two layers:

A High-Level API (HLAPI) wraps the low-level API and provides a convenient interface for common operations.
A Low-Level API (LLAPI) provides maximum flexibility for more advanced oeprations.

The system breaks down an HTTP transaction into the following operations:

Each of these operations are managed by a specific type of object, which you can use to customize and control aspects of the transaction:

An
```
UploadHandler
```
object handles transmission of data to the server.
A
```
DownloadHandler
```
object handles receipt, buffering, and postprocessing of data received from the server.
A
```
UnityWebRequest
```
object manages the other two objects, and also handles HTTP flow control. This object is where custom headers and URLs are defined, and where error and redirect information is stored.

The following is a high level overview of a HTTP transaction:

Create a
```
UnityWebRequest
```
object.
Configure the
```
UnityWebRequest
```
object.
- Set custom headers.
- Set HTTP verb (such as
```
GET
```
  ,
```
POST
```
  ,
```
HEAD
```
  - custom verbs are permitted on all platforms).
- Set URL.
(Optional) Create an upload handler and attach it to the web request.
- Provide data to be uploaded.
- Provide an HTTP form to be uploaded.
(Optional) Create a download handler and attach it to the web request.
Send the web request.
- From a coroutine, you can
```
yield
```
  the result of the
```
UnityWebRequest.SendRequest
```
  call to wait for the request to complete.
(Optional) Read received data from the download handler.
(Optional) Read error information, HTTP status code, and response headers from the
```
UnityWebRequest
```
object.

For a detailed code example that illustrates these steps, refer to the API documentation for

UploadHandlerRaw