WebRequest

A robust HTTP client solution for Unity, offering flexible API management, automatic retries, and comprehensive request handling using .NET's HttpClient.

In One Line

REST assured, your requests are in good hands!

Overview

AceLand WebRequest is a modern web request solution designed specifically for Unity projects, providing a fluent interface for API calls with built-in error handling, retry mechanisms, and API section management. It uses .NET's HttpClient instead of UnityWebRequest for better performance and more control.

Package Info

display name

AceLand WebRequest

package name

com.aceland.webrequest

latest version

2.2.3

namespace

AceLand.WebRequest

git repository

https://github.com/parsue/com.aceland.webrequest.git

dependencies

com.aceland.library: 2.2.1
com.aceland.disposable: 1.0.0
com.aceland.projectsetting: 1.0.0
com.aceland.taskutils: 2.2.1
com.unity.nuget.newtonsoft-json: 3.2.1

Why Use It?

Modern Architecture: Built on .NET's HttpClient for better performance and reliability
Flexible API Management: Test and switch between different API configurations in editor
Built-in Retry Logic: Automatic retry mechanism with configurable intervals
Type-Safe Builder Pattern: Fluent interface for building requests with compile-time safety
Comprehensive Error Handling: Detailed error logging and exception management
Multiple Content Types: Support for JSON, Form, and Multipart request types

Key Features

Custom retry intervals and timeout settings
Comprehensive logging system with different build levels
HTTPS enforcement option
Automatic timestamp header injection
JSON validation before sending
Support for cancellation tokens
Editor tools for API section management

Project Settings

Logging

---

Logging Level

Level of Logging on web request default: BuildLevel.Production

Result Logging Level

Level of Logging on request success

default: BuildLevel.DevelopmentBuild

Full Logging Level

Level of Logging on all request logs content.

Logs will contain all parameters, headers and body contents. default: BuildLevel.DevelopmentBuild

Checking Options

---

Check Json Before Send

Check given content is a valid json before send request. This may be expensive if big content. Default: false

Force Https Scheme

Require request url is https if true. Otherwise http will also ok. Default: true

Request Options

---

Request Timeout

Default timeout if not set in request handle. Default: 3000 ms

Long Request Timeout

Default long request timeout. It will be set if building request handle with long request. Default: 15000 ms

Request Retry

How many times will retry on connection error including timeout. Default: 3

Retry Interval

Interval between each retry. Default: [ 400, 800, 1600, 3200, 6400, 12800, 25600] in ms

Header Auto Fill

---

Add Time In Header

Add send time in header automatically. Default: true

Time Key

key of Time in header. default: Time

Auto Fill Headers

Add default headers on each Request. Same headers will be covered by WithHeaders options on building Request. Default: { "User-Agent", "Mozilla/5.0" }

API Sections Profiles

---

Api Sections (c)

This is a list of API Sections Profiles. title bar: + add new field - delete last field

in line: - delete field * apply to Current API Section

Default API Section

---

Section Name

[Lock] default API section.

Api Url

[Lock] API URL of default section.

API

// base API
Request

// Value
string defaultSectionName = Request.DefaultSection;
string defaultApiUrl = Request.DefaultApiUrl;
string apiUrl = Request.SectionApiUrl("sectionName");
IEnumerable<HeaderData> defaultHeaders = Request.DefaultHeaders;
IEnumerable<HeaderData> header = Request.SectionHeaders("sectionName");

API Section

API section is a profile built with scriptable object.

Create a project and set the values, then set in Project Settings.

In Project Settings, find API Sections Profiles section, and press + to add a new row. Add more sections as your needs.

Press * to set default. the default section will show in the below section.

Basic Usage

Building request is easy.

start with request method
chain with url first
add parameters if necessary
add Header if necessary, see Project Settings
add Body if necessary, see Request Body

// Create a GET Request Handler
// default section url: https://api.abc.com
// request url: https://api.example.com/data?clientid:a123456
IRequestHandle request = Request.Get()
    .WithoutSection()
    .WithUrl("https://api.example.com/data")
    .WithParam("clientid", "a123456")
    .WithHeader("User-Agent", "MyUnityApp/1.0")
    .WithHeader("API-KEY", "abcde-5d8d1fe")
    .Build();
    
// Create a POST Request Handler
// default section url: https://api.abc.com
// request url: https://api.abc.com/users?clientid:a123456
IRequestHandle request = Request.Post()
    .WithUrl("/users")    // combine with default section url
    .WithParam("clientId", "a123456")
    .WithJsonContent()
    .WithContent("{\"name\": \"John\"}")
    .WithHeader("Authorization", "Bearer token")
    .WithTimeout(7500)
    .Build();
    
// Create a POST Request Handler with Multipart form data with file
// dev section url: https://api.abc.com/dev
// request url: https://api.abc.com/dev/upload?clientid:a123456
IRequestHandle request = Request.Post()
    .WithSection("dev")
    .WithUrl("/upload")    // combine with dev section url
    .WithParam("clientId", "a123456")
    .WithMultipartContent()
    .WithStreamData("file", "path/to/file.jpg", "image.jpg")
    .WithContent("description", "Profile photo")
    .Build();

After created a request, call Send() method.

// Send the request and get reponse
// if server return non json string,
//    it will become { "message" : "server response" }
JToken response = await request.Send();
    
// Send the request and receive specified type of data
YourData response = await request.Send<YourData>();

It's recommended to work with Promise for thread and exception safe.

request.Send()
    .Then(OnJsonResponse)
    .Catch(Debug.LogError);
    
request.Send<YourData>()
    .Then(OnSuccess)
    .Catch(Debug.LogError);
    
private void OnJsonResponse(JToken response) { }
private void OnSuccess(YourData response) { }

Request Body

In real-world experience, servers, proxies or clients will ignore body on methods even allowed by spec.

For a promise of communictaion, our request handle will follow the modern experience.

About Delete method, please avoid sending a body. Many servers ignore it. Semantics are unclear.

Exception Handling

IRequestHandle will throw serval exception types on catching errors.

A Task will be return on calling Send(). It's recommended to work with Promise for thread safe.

WebRequesting()
    .Then(OnSuccess)
    .Catch<WebException>(OnConnectionError)
    .Catch<HttpServerErrorException>(OnServerError)
    .Catch<HttpErrorException>(OnHttpError)
    .Catch<OperationCanceledException>(OnUserCanceled)
    .Catch(Debug.LogError)
    .Final(() => Debug.Log("WebRequesting: Finished"));

private async Task<ResponseData> WebRequesting()
{
    var url = "https://www.orangeisbetterthenapple.io";
    var request = Request.Get()
        .WithUrl(url)
        .WithHeader("User-Agent", "MyUnityApp/1.0")
        .Build();
    return request.Send<ResponseData>(); 
}

private void OnSuccess(ResponseData response)
{
    // stuff
}

private void OnHttpError(HttpErrorException e)
{
    var msg = e.StatusCode switch
    {
        HttpStatusCode.Unauthorized => "Auth Failed. Auth Token removed.",
        >= HttpStatusCode.InternalServerError => $"Server Error: - {e.Message}",
        HttpStatusCode.TooManyRequests => $"Server Busy: - {e.Message}",
        _ => $"Http Error: {e.Message}"
    };
    Debug.LogWarning(msg);
}

For example, there is a Weather Widget on canvas. It will refresh every set time.

using System.Threading;
using System.Threading.Tasks;
using AceLand.TaskUtils;
using AceLand.WebRequest;
using TMPro;
using UnityEngine;
using UnityEngine.UI;

public class TestWeatherWidget : MonoBehaviourr
{
    [Header("Weather Widget")]
    // WeatherProfile contains sprite of weather state
    [SerializeField] private WeatherProfile profile;
    // HongKongLocations contains districts and coordinates
    [SerializeField] private HongKongLocations location = HongKongLocations.CentralAndWestern;
    [SerializeField] private int updateInterval = 180;
    [SerializeField] private Image weatherIcon;
    [SerializeField] private TextMeshProUGUI tempLabel;
    [SerializeField] private TextMeshProUGUI apparentTempLabel;
    
    // setup API
    // default section url: https://api.open-meteo.com/v1
    private const string API = "/forecast";
   
    private Promise _promise;
    
    private void OnEnable()
    {
        RequestWebData();
    }

    private void OnDisable()
    {
        _promise?.Dispose();
    }
    
    private void UpdateWeather(WeatherWidgetData data)
    {
        weatherIcon.sprite = profile.GetIcon(data.WeatherCode, data.IsDay);
        tempLabel.text = data.Temperature;
        apparentTempLabel.text = $"Apparent: {data.ApparentTemperature}";
    }

    private void RequestWebData()
    {
        var (latitude, longitude) = location.ToGeoData();
        
        // create request
        IRequestHandle request = Request.Get()
            .WithUrl(API)
            .WithParam("latitude", latitude.ToString("F4"))
            .WithParam("longitude", longitude.ToString("F4"))
            .WithParam("current", "temperature_2m,weather_code,rain,cloud_cover,showers,apparent_temperature,is_day")
            .WithParam("timezone", "auto")
            .WithParam("forecast_days", "1")
            .Build();

        // send request
        _promise = request.Send<WeatherWebData>()
            .Then(result =>
            {
                // convert data
                WeatherWidgetData widgetData = result.ToWidgetData(location);
                // use data
                UpdateWeather(widgetData);
            })
            .Catch<WebException>(e =>
                Debug.LogError($"connection error: {e.Message}", this))
            .Catch<HttpServerErrorException>(e =>
                Debug.LogError($"server error: {e.Message}", this))
            .Catch<HttpErrorException>(e =>
                Debug.LogError($"request error: {e.Message}", this))
            .Catch<JsonReaderException>(e =>
                Debug.LogError($"error on extracting data from server: {e.Message}", this))
            .Catch<OperationCanceledException>(e =>
                Debug.LogWarning("request canceled by user.", this))
            .Catch(e =>
                Debug.LogWarning($"other exception: {e}", this))
            .Final(() =>
            {
                // prepare next call
                WaitForRefresh();
                // dispose current request
                request.Dispose();
            });
    }

    private void WaitForRefresh()
    {
        _promise = Promise.WaitForSeconds(updateInterval)
            .Then(RequestWebData);
    }
}

Work with Promise Awaiter for thread-safe and clear coding structure.

Please read Task Utils for details.

Advanced Sample

This is a sample of building a User Authorization API serivce and how to use it. An API section profile is already set in project settings and set as default.

Following library and packages are using in above example:

using System.Threading.Tasks;
using AceLand.WebRequest;

// create UserAPI Service
public sealed class UserAPI
{
    // prepare all api urls.
    private const string BASIC_AUTH_URL = "/basic-auth";
    
    private static IRequestHandle _request;
    
    // create a Promise to disposal request handle on finished
    public static Promise<UserData> BasicAuth(string user, string password)
    {
        // build Request Handle
        _request = Request.Get()
            .WithUrl(BASIC_AUTH_URL )
            .WithParam("user", user)
            .WithParam("Password", password)
            .Build();
        
        // await response with specified type
        return _request.Send<UserData>()
            .Final(_request.Disposal);
    }
    
    public static async CancelBasicAuth()
    {
        _request?.Cancel();
    }
}

using AceLand.Library.Optional;

// Event for User Login
public interface IUserLoginEvent { }
public interface IUserCancelLoginEvent { }
public readonly struct UserLoginData : IValidatable
{
    public readonly string User;
    public readonly string Password;
    private readonly UserLoginDataValidator _validator;

    // use Optional for null handling
    public UserLoginData(Option<string> user, Option<string> password)
    {
        User = user.Map(t => t.Trim()).Reduce(() => string.Empty);
        Password = password.Map(t => t.Trim()).Reduce(() => string.Empty);
        _validator = new UserLoginDataValidator();
    }

    // Validate User Login Data
    public bool Validate() => _validator.Validate(this);
}

// Event for User Authorization Service
public interface IUserAuthEvent { }
public enum UserAuthState
{
    None, Authorized, WrongUserPasswd,
    ConnectionError, RequestError, ResponseError, AuthError
}

using AceLand.Library.Extensions;

public interface IValidatable
{
    bool Validate();
}

public abstract class Validator<T> where T : IValidatable
{
    public virtual bool Validate(T data) => false;
}

public sealed class UserLoginDataValidator : Validator<UserLoginData>
{
    private const int USERNAME_MIN_LENGTH = 8;
    private const int PASSWORD_MIN_LENGTH = 8;

    public override bool Validate(UserLoginData data) =>
        !data.User.IsNullOrEmptyOrWhiteSpace() &&
        !data.Password.IsNullOrEmptyOrWhiteSpace() &&
        data.User.Length > USERNAME_MIN_LENGTH &&
        data.Password.Length > PASSWORD_MIN_LENGTH;
}

using System;
using AceLand.EventDriven.Bus;
using AceLand.Library.Mono;
using AceLand.TaskUtils;

public class UserAuthorization : Singleton<UserAuthorization>
{
    private UserAuthState _userAuthState;
    private UserData _userData;
    private bool _busy;
    
    private void OnEnable()
    {
        // Listen to events
        EventBus.Event<IUserLoginEvent>()
            .WithListener<UserLoginData>(OnUserLogin)
            .WithKickStart()
            .Listen();
            
        EventBus.Event<IUserCancelLoginEvent >()
            .WithListener(OnUserCancelLogin)
            .WithKickStart()
            .Listen();
    }
    
    private void OnDisable()
    {
        // Unlisten from IUserLoginEvent
        EventBus.Event<IUserLoginEvent>()
            .Unlisten<UserLoginData>(OnUserLogin);
            
        EventBus.Event<IUserCancelLoginEvent >()
            .Unlisten(OnUserCancelLogin);
    }

    private void OnUserLogin(object sender, UserLoginData data)
    {
        if (sender is not UiLoginHandle)
            throw new Exception($"Illegal User Auth Sender detected: {typeof(sender)}");
    
        // checking policies
        if (!data.Validate())
        {
            OnAuthEvent(UserAuthState.WrongUserPasswd);
            return;
        }
        
        // start user auth
        HandleUserAuth(data);
    }
    
    private void OnUserCancelLogin(object sender)
    {
        if (sender is not UiLoginHandle)
            throw new Exception($"Illegal User Auth Sender detected: {typeof(sender)}");
        
        // cancel user auth
        CancelUserAuth();
    }

    private void HandleUserAuth(UserLoginData data)
    {
        if (_busy) return;
        if (_userAuthState is UserAuthState.Authorized)
        {
            OnAuthSuccess(_userData);
            return;
        }
        
        _busy = true;
        
        // Use Promise Awaiter to handle request
        UserAPI.BasicAuth(data.User, data.Password)
            .Then(OnAuthSuccess)
            .Catch<WebException>(_ => OnAuthEvent(UserAuthState.ConnectionError))
            .Catch<HttpRequestException>(_ => OnAuthEvent(UserAuthState.RequestError))
            .Catch<JsonReaderException>(_ => OnAuthEvent(UserAuthState.ResponseError))
            .Catch<OperationCanceledException>(_ => OnAuthEvent(UserAuthState.AuthError))
            .Catch(_ => OnAuthEvent(UserAuthState.AuthError))
            .Final(OnAuthFinish);
    }
    
    private void CancelUserAuth()
    {
        if (!_busy) return;
        UserAPI.CancelBasicAuth();
    }

    private void OnAuthSuccess(UserData userData)
    {
        _userData = userData;
        OnAuthEvent(UserAuthState.Authorized);
    }

    private void OnAuthEvent(UserAuthState state)
    {
        _userAuthState = state;
        // raise event IUserAuthEvent
        EventBus.Event<IUserAuthEvent>()
            .WithSender(this)
            .WithData(state)
            .Raise();
    }

    private void OnAuthFinish()
    {
        _busy = false;
    }
}

using AceLand.Library.Optional;
using UnityEngine;

public class UiLoginHandle : MonoBehaviour
{
    // use Optional for null handling
    private Option<string> _username;
    private Option<string> _password;

    // link to Input Component
    public void OnUsernameInput(string value) =>
        _username = value.ToOption();
    
    // link to Input Component    
    public void OnPasswordInput(string value) =>
        _password = value.ToOption();

    // link to Button Component
    public void OnLoginButtonPressed()
    {
        // create data
        UserLoginData data = new UserLoginData(_username, _password);
        
        // raize event
        EventBus.Event<IUserLoginEvent>()
            .WithSender(this)
            .WithData(data)
            .Raise();
    }
    
    public void OnCancelButtonPressed()
    {
        _username = string.Empty;
        _password = string.Empty;
        
        // raize event
        EventBus.Event<IUserCancelLoginEvent>()
            .WithSender(this)
            .WithData(data)
            .Raise();
    }
}

PreviousExtensions NextChange Log

Last updated 10 days ago

In One Line

Overview

Package Info

Why Use It?

Key Features

Project Settings

API

API Section

Basic Usage

Request Body

Exception Handling

Sample of Weather Widget

Advanced Sample