README.md

com.utilities.rest

A Utilities.Rest package for the Unity Game Engine.

Installing

Requires Unity 2021.3 LTS or higher.

The recommended installation method is though the unity package manager and OpenUPM.

Via Unity Package Manager and OpenUPM

• Open your Unity project settings
• Select the Package Manager
• Add the OpenUPM package registry:
  • Name: OpenUPM
  • URL: https://package.openupm.com
  • Scope(s):
    • com.utilities
• Open the Unity Package Manager window
• Change the Registry from Unity to My Registries
• Add the Utilities.Rest package

Via Unity Package Manager and Git url

• Open your Unity Package Manager
• Add package from git url: https://github.com/RageAgainstThePixel/com.utilities.rest.git#upm

  Note: this repo has dependencies on other repositories! You are responsible for adding these on your own.

  • com.utilities.async
  • com.utilities.extensions

---

Documentation

This library aims to provide basic support for common RESTful state transactions with most web APIs.

Advanced features includes progress notifications, authentication and native multimedia downloads of asset bundles, textures, audio clips with file caching.

Table of contents

• Authentication
• Rest Parameters
• Get
• Post
  • Server Sent Events ⚠️
  • Data Received Callbacks
• Put
• Patch
• Delete
• Download Multimedia
  • Caching
  • Files
  • Textures
  • Audio
    • Streaming
  • Asset Bundles

Authentication

// Get a basic auth header encoded to base64 string:
var basicAuthentication = Rest.GetBasicAuthentication("username", "password");

// Get a bearer auth token header
var bearerToken = Rest.GetBearerOAuthToken("authToken");

These methods will generate the necessary data to apply to your authentication headers, they DO NOT set the authentication for any Rest calls.

Rest Parameters

Rest parameters have been bundled into a single object to make the method signatures a bit more uniform, these can be provided with all requests made using the com.utilities.rest library to control how the operation performs.

var restParameters = new RestParameters(
    headers, // Optional, header information for the request.
    progressCallback, // Optional, Progress callback handler for the request.
    timeout, // Optional, time in seconds before the request expires. Default is -1.
    disposeDownloadHandler, // Optional, dispose the DownloadHandler. Default is true.
    disposeUploadHandler, // Optional, dispose the UploadHandler. Default is true.
    certificateHandler, // Optional, certificate handler for the request.
    disposeCertificateHandler, // Optional, dispose the CertificateHandler. Default is true.
    cacheDownloads, // Optional, cache downloaded content. Default is true.
    debug); // Optional, enable debug output of the request. Default is false.

// Rest call passing a pre-configured set of RestParameters
var response = await Rest.GetAsync("www.your.api/endpoint", restParameters);

If you require any of the above options when making calls, ensure to add a RestParameters construct to the request, as shown above.

Pro Tip: If you have multiple requests using the same "Parameters", then cache a single instance of the RestParameters and use this for all calls instead of recreating it for each request.

Get

var response = await Rest.GetAsync("www.your.api/endpoint");
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Post

var form = new WWWForm();
form.AddField("fieldName", "fieldValue");
var response = await Rest.PostAsync("www.your.api/endpoint", form);
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Server Sent Events

Warning

This callback was recently refactored from Action<Response, ServerSentEvent> to Func<Response, ServerSentEvent, Task>. To update this callback without asynchronous calls, just add await Task.CompletedTask; at the end of your callback function.

var jsonData = "{\"data\":\"content\"}";
var response = await Rest.PostAsync("www.your.api/endpoint", jsonData, async (sseResponse, ssEvent) => {
    Debug.Log(ssEvent);
    await Task.CompletedTask;
});
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Data Received Callbacks

var jsonData = "{\"data\":\"content\"}";
var response = await Rest.PostAsync("www.your.api/endpoint", jsonData, dataReceivedEventCallback => {
    // eventCallback type is Rest.Response
    Debug.Log(dataReceivedEventCallback.Body);
});
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Put

var jsonData = "{\"data\":\"content\"}";
var response = await Rest.PutAsync("www.your.api/endpoint", jsonData);
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Patch

var jsonData = "{\"data\":\"content\"}";
var response = await Rest.PatchAsync("www.your.api/endpoint", jsonData);
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Delete

var response = await Rest.DeleteAsync("www.your.api/endpoint");
// Validates the response for you and will throw a RestException if the response is unsuccessful.
response.Validate(debug: true);

Multimedia

Caching

You can set the parent directory of the download cache to one of the following predefined locations:

• Application.temporaryCachePath (default)
• Application.persistentDataPath
• Application.dataPath
• Application.streamingAssetsPath

The actual cache directory will be a subfolder named download_cache inside of the parent DownloadCacheDirectory.

// cache directory defaults to {Application.temporaryCachePath}/download_cache/
Debug.Log(Rest.DownloadCacheDirectory);

// cache directory can be set to one of:
// Application.temporaryCachePath,
// Application.persistentDataPath,
// Application.dataPath,
// Application.streamingAssetsPath
Rest.DownloadLocation = Application.streamingAssetsPath;

var uri = "www.url.to/remote/resource";

if (Rest.TryGetDownloadCacheItem(uri, out var cachedFilePath))
{
    // the local downloaded file in the cache
    Debug.Log(cachedFilePath);

    // Delete a locally cached item.
    if (Rest.TryDeleteCacheItem(uri))
    {
        Debug.Log($"Deleted {cachedFilePath}");
    }
}
else
{
    Debug.Log($"Unable to download from {uri}");
}

// Clear the whole download cache directory
Rest.DeleteDownloadCache();

Files

Download a file.

var downloadedFilePath = await Rest.DownloadFileAsync("www.your.api/your_file.pdf");

if (!string.IsNullOrWhiteSpace(downloadedFilePath) && File.Exists(downloadedFilePath))
{
    Debug.Log(downloadedFilePath);
}
else
{
    Debug.LogError($"Failed to download file!");
}

Download a file, then return the raw byte data.

var downloadedBytes = await Rest.DownloadFileBytesAsync("www.your.api/your_file.pdf");

if (downloadedBytes != null && downloadedBytes.Length > 0)
{
    // do some custom loading of your binary file.
    Debug.Log(downloadedBytes.Length);
}
else
{
    Debug.LogError($"Failed to download file!");
}

Download raw file bytes directly into memory.

This request does not cache data

var downloadedBytes = await Rest.DownloadBytesAsync("www.your.api/your_file.pdf");

if (downloadedBytes != null && downloadedBytes.Length > 0)
{
    Debug.Log(downloadedBytes.Length);
}
else
{
    Debug.LogError($"Failed to download file!");
}

Textures

Pro Tip: This also works with local file paths to load textures async at runtime!

var texture = await Rest.DownloadTextureAsync("www.your.api/your_file.png");

if (texture != null)
{
    // assign it to your renderer
    rawImage.texture = texture;
}
else
{
    Debug.LogError($"Failed to download texture!");
}

Audio

Pro Tip: This also works with local file paths to load audio clips async at runtime!

var audioClip = await Rest.DownloadAudioClipAsync("www.your.api/your_file.ogg", AudioType.OGGVORBIS);

if (audioClip != null)
{
    // assign it to your audio source
    audioSource.clip = audioClip;
    audioSource.PlayOneShot(audioClip);
}
else
{
    Debug.LogError($"Failed to download audio clip!");
}

Audio Streaming

Streams an audio file from disk or remote resource as soon as enough data has been loaded.

Unsure if this is working correctly as Unity doesn't seem to respect streaming when setting DownloadHandlerAudioClip.streamAudio to true. Seems to work better for local files on disk than remote resources. Seems to only work for mp3 files.

var audioClip = await Rest.StreamAudioAsync("local/path/to/your_file.mp3", AudioType.MPEG, onStreamPlaybackReady =>
{
    audioSource.PlayOneShot(onStreamPlaybackReady);
});
// you can assign the fully downloaded clip to your audio source if desired
audioSource.clip = audioClip;

Asset Bundles

var bundleOptions = new AssetBundleRequestOptions();
var assetBundle = await Rest.DownloadAssetBundleAsync("www.your.api/asset.bundle", bundleOptions);

if (assetBundle != null)
{
    var cube = assetBundle.LoadAsset<GameObject>("Cube");
    Instantiate(cube);
}
else
{
    Debug.LogError($"Failed to download and load asset bundle!");
}