Nethereum.Util.Rest

NuGet: Nethereum.Util.Rest | Source: src/Nethereum.Util.Rest/ Generic REST client abstraction and implementation for HTTP API interactions with JSON serialization support.

Overview

Nethereum.Util.Rest provides a lightweight wrapper around HttpClient for making REST API calls with automatic JSON serialization/deserialization. It's designed to simplify HTTP communication in Nethereum components and user applications.

Key Features:

Generic interface for RESTful HTTP operations (GET, POST, PUT, DELETE)
Automatic JSON serialization/deserialization using System.Text.Json (.NET 8+) or Newtonsoft.Json (older versions)
Support for custom headers including Bearer token authentication
Multipart form data support for file uploads
HttpClient extension methods with built-in auth support
Dependency injection friendly with IRestHttpHelper interface
Used internally by Nethereum.Beaconchain, Nethereum.DataServices, and other packages

Installation

dotnet add package Nethereum.Util.Rest

Or via Package Manager Console:

Install-Package Nethereum.Util.Rest

Dependencies

External:

System.Text.Json (.NET 8+) or Newtonsoft.Json (older frameworks)
System.Net.Http.HttpClient

Nethereum:

None (this is a foundational utility package)

Key Concepts

IRestHttpHelper Interface

The IRestHttpHelper interface provides a generic abstraction for REST operations:

public interface IRestHttpHelper
{
    Task<T> GetAsync<T>(string path, Dictionary<string, string> headers = null);
    Task<TResponse> PostAsync<TResponse, TRequest>(string path, TRequest request, Dictionary<string, string> headers = null);
    Task<TResponse> PutAsync<TResponse, TRequest>(string path, TRequest request, Dictionary<string, string> headers = null);
    Task DeleteAsync(string path, Dictionary<string, string> headers = null);
    Task<TResponse> PostMultipartAsync<TResponse>(string path, MultipartFormDataRequest request, Dictionary<string, string> headers = null);
}

RestHttpHelper Implementation

Concrete implementation that wraps HttpClient and handles JSON serialization automatically.

HttpClient Extensions

Extension methods for HttpClient with built-in Bearer token authentication support (NET 5.0+).

JSON Serialization Strategy

.NET 8+: Uses System.Text.Json for better performance
Older versions: Uses Newtonsoft.Json for compatibility
Transparent to API consumers - same interface across all frameworks

Quick Start

using Nethereum.Util.Rest;
using System.Net.Http;

// Create REST helper
var httpClient = new HttpClient();
var restHelper = new RestHttpHelper(httpClient);

// Make a GET request
var data = await restHelper.GetAsync<MyDataModel>("https://api.example.com/data");

// Make a POST request
var response = await restHelper.PostAsync<ResponseModel, RequestModel>(
    "https://api.example.com/submit",
    new RequestModel { Value = "test" }
);

Usage Examples

Example 1: Basic GET Request with Custom Headers

using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;

// Create REST helper
var restHelper = new RestHttpHelper(new HttpClient());

// Define custom headers
var headers = new Dictionary<string, string>
{
    { "accept", "application/json" }
};

// Make GET request
var result = await restHelper.GetAsync<ApiResponse>(
    "https://api.example.com/v1/data",
    headers
);

public class ApiResponse
{
    public string Status { get; set; }
    public object Data { get; set; }
}

Example 2: Dependency Injection Pattern (Real Example from BeaconApiClient)

Nethereum.Beaconchain.BeaconApiClient is a real consumer of IRestHttpHelper — its constructors accept either an HttpClient or an IRestHttpHelper directly (for testing), and it exposes light-client operations through its LightClient property.

using Nethereum.Beaconchain;
using Nethereum.Beaconchain.LightClient.Responses;
using Nethereum.Util.Rest;
using System.Net.Http;
using System.Threading.Tasks;

// Constructor with HttpClient
var beaconClient = new BeaconApiClient("https://beacon-node.example.com", new HttpClient());

// Constructor with IRestHttpHelper (for testing)
IRestHttpHelper fakeRestHelper = null; // supply a test double
var testableClient = new BeaconApiClient("https://beacon-node.example.com", fakeRestHelper);

// Light-client calls go through the LightClient property (ILightClientApi)
LightClientBootstrapResponse bootstrap = await beaconClient.LightClient.GetBootstrapAsync(blockRoot);

Example 3: 4byte.directory API Integration (Real Example)

using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;

public class FourByteDirectoryService
{
    public const string BaseUrl = "https://www.4byte.directory";
    private IRestHttpHelper _restHttpHelper;

    public FourByteDirectoryService()
    {
        _restHttpHelper = new RestHttpHelper(new HttpClient());
    }

    public FourByteDirectoryService(IRestHttpHelper restHttpHelper)
    {
        _restHttpHelper = restHttpHelper;
    }

    // Get function signature by hex signature (e.g., "0xa9059cbb")
    public Task<FourByteDirectoryResponse> GetFunctionSignatureByHexSignatureAsync(
        string hexSignature)
    {
        var url = $"{BaseUrl}/api/v1/signatures/?hex_signature={hexSignature}";
        return GetDataAsync<FourByteDirectoryResponse>(url);
    }

    // Get function signature by text (e.g., "transfer(address,uint256)")
    public Task<FourByteDirectoryResponse> GetFunctionSignatureByTextSignatureAsync(
        string textSignature)
    {
        var url = $"{BaseUrl}/api/v1/signatures/?text_signature={textSignature}";
        return GetDataAsync<FourByteDirectoryResponse>(url);
    }

    private async Task<T> GetDataAsync<T>(string url)
    {
        var headers = new Dictionary<string, string>
        {
            { "accept", "application/json" }
        };

        return await _restHttpHelper.GetAsync<T>(url, headers);
    }
}

Example 4: Sourcify Contract Verification API (Real Example)

using Nethereum.ABI.CompilationMetadata;
using Nethereum.DataServices.Sourcify.Responses;
using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;

public class SourcifyApiService
{
    public const string BaseUrl = "https://sourcify.dev/server/";
    public const string BaseUrlMeta = "https://repo.sourcify.dev/";
    private IRestHttpHelper restHttpHelper;

    public SourcifyApiService()
    {
        restHttpHelper = new RestHttpHelper(new HttpClient());
    }

    public SourcifyApiService(HttpClient httpClient)
    {
        restHttpHelper = new RestHttpHelper(httpClient);
    }

    // Get compilation metadata for verified contract
    public Task<CompilationMetadata> GetCompilationMetadataAsync(
        long chain,
        string address,
        bool fullMatch = true)
    {
        var matchType = fullMatch ? "full_match" : "partial_match";
        var url = $"{BaseUrlMeta}/contracts/{matchType}/{chain}/{address}/metadata.json";
        return GetDataAsync<CompilationMetadata>(url);
    }

    // Get source files for verified contract
    public Task<List<SourcifyContentFile>> GetSourceFilesFullMatchAsync(
        long chain,
        string address)
    {
        var url = $"{BaseUrl}/files/{chain}/{address}";
        return GetDataAsync<List<SourcifyContentFile>>(url);
    }

    private Task<T> GetDataAsync<T>(string url)
    {
        var headers = new Dictionary<string, string>
        {
            { "accept", "application/json" }
        };

        return restHttpHelper.GetAsync<T>(url, headers);
    }
}

Example 5: POST Request with Custom Object

using Nethereum.Util.Rest;
using System.Net.Http;

var restHelper = new RestHttpHelper(new HttpClient());

// Define request and response models
public class CreateUserRequest
{
    public string Username { get; set; }
    public string Email { get; set; }
}

public class CreateUserResponse
{
    public int UserId { get; set; }
    public string Status { get; set; }
}

// Make POST request
var request = new CreateUserRequest
{
    Username = "alice",
    Email = "alice@example.com"
};

var response = await restHelper.PostAsync<CreateUserResponse, CreateUserRequest>(
    "https://api.example.com/users",
    request
);

Console.WriteLine($"Created user ID: {response.UserId}");

Example 6: PUT Request for Updates

using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;

var restHelper = new RestHttpHelper(new HttpClient());

public class UpdateProfileRequest
{
    public string DisplayName { get; set; }
    public string Bio { get; set; }
}

public class UpdateProfileResponse
{
    public bool Success { get; set; }
    public string Message { get; set; }
}

// Update with custom headers
var headers = new Dictionary<string, string>
{
    { "X-Api-Version", "2.0" }
};

var updateRequest = new UpdateProfileRequest
{
    DisplayName = "Alice Smith",
    Bio = "Blockchain developer"
};

var result = await restHelper.PutAsync<UpdateProfileResponse, UpdateProfileRequest>(
    "https://api.example.com/profile/123",
    updateRequest,
    headers
);

Example 7: DELETE Request

using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;

var restHelper = new RestHttpHelper(new HttpClient());

// Delete with authentication header
var headers = new Dictionary<string, string>
{
    { "Authorization", "Bearer YOUR_TOKEN_HERE" }
};

await restHelper.DeleteAsync(
    "https://api.example.com/items/456",
    headers
);

Console.WriteLine("Item deleted successfully");

Example 8: HttpClient Extension Methods with Bearer Auth (.NET 5+)

#if NET5_0_OR_GREATER
using Nethereum.Util.Rest;
using System.Net.Http;

var httpClient = new HttpClient();
string bearerToken = "your-jwt-token";

// GET with Bearer token
var userData = await httpClient.GetAsync<UserProfile>(
    "https://api.example.com/user/profile",
    bearerToken
);

// POST with Bearer token
var createData = new { name = "New Item", value = 100 };
var createResponse = await httpClient.PostAsync<CreateResponse>(
    "https://api.example.com/items",
    createData,
    bearerToken
);

// PUT with Bearer token
var updateData = new { value = 200 };
var updateResponse = await httpClient.PutAsync<UpdateResponse>(
    "https://api.example.com/items/123",
    updateData,
    bearerToken
);

// DELETE with Bearer token (returns int status)
var deleteStatus = await httpClient.DeleteAsync(
    "https://api.example.com/items/123",
    bearerToken
);
#endif

Example 9: Multipart Form Data for File Uploads

using Nethereum.Util.Rest;
using System.Collections.Generic;
using System.Net.Http;

var restHelper = new RestHttpHelper(new HttpClient());

// Create multipart request
var multipartRequest = new MultipartFormDataRequest
{
    Fields = new List<MultipartField>
    {
        new MultipartField { Name = "title", Value = "My Contract" },
        new MultipartField { Name = "network", Value = "mainnet" }
    },
    Files = new List<MultipartFile>
    {
        new MultipartFile
        {
            FieldName = "file",
            FileName = "Token.sol",
            Content = "pragma solidity ^0.8.0; contract Token { ... }",
            ContentType = "text/plain"
        }
    }
};

// Add authorization header
var headers = new Dictionary<string, string>
{
    { "Authorization", "Bearer YOUR_TOKEN" }
};

// Upload file
var uploadResponse = await restHelper.PostMultipartAsync<UploadResponse>(
    "https://api.example.com/upload",
    multipartRequest,
    headers
);

Console.WriteLine($"Upload status: {uploadResponse.Status}");

public class UploadResponse
{
    public string Status { get; set; }
    public string FileId { get; set; }
}

API Reference

IRestHttpHelper

Generic REST client interface.

public interface IRestHttpHelper
{
    // GET request with JSON deserialization
    Task<T> GetAsync<T>(string path, Dictionary<string, string> headers = null);

    // POST request with JSON serialization/deserialization
    Task<TResponse> PostAsync<TResponse, TRequest>(
        string path,
        TRequest request,
        Dictionary<string, string> headers = null);

    // PUT request with JSON serialization/deserialization
    Task<TResponse> PutAsync<TResponse, TRequest>(
        string path,
        TRequest request,
        Dictionary<string, string> headers = null);

    // DELETE request
    Task DeleteAsync(string path, Dictionary<string, string> headers = null);

    // POST multipart form data (file uploads)
    Task<TResponse> PostMultipartAsync<TResponse>(
        string path,
        MultipartFormDataRequest request,
        Dictionary<string, string> headers = null);
}

RestHttpHelper additionally exposes a lower-level method not on the interface:

// Send a fully-constructed HttpRequestMessage directly; returns the raw response, so the caller owns the body and MaxResponseBytes does not apply
public async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request);

RestHttpHelper

Concrete implementation of IRestHttpHelper.

public class RestHttpHelper : IRestHttpHelper
{
    // Constructor - optionally provide HttpClient
    public RestHttpHelper(HttpClient httpClient = null);

    public const long DefaultMaxResponseBytes = 32L * 1024 * 1024;
    public long MaxResponseBytes { get; set; } = DefaultMaxResponseBytes;

    // Implements all IRestHttpHelper methods
    // Throws Exception on non-success status codes
}

HttpClientExtensions (.NET 5.0+)

Extension methods for HttpClient with Bearer token authentication.

public static class HttpClientExtensions
{
    // GET with Bearer token
    public static Task<T> GetAsync<T>(
        this HttpClient httpClient,
        string url,
        string token);

    // POST with Bearer token and response
    public static Task<T> PostAsync<T>(
        this HttpClient httpClient,
        string url,
        object data,
        string token);

    // POST with Bearer token returning HttpResponseMessage
    public static Task<HttpResponseMessage> PostAsync(
        this HttpClient httpClient,
        string url,
        object data,
        string token);

    // PUT with Bearer token
    public static Task<T> PutAsync<T>(
        this HttpClient httpClient,
        string url,
        object data,
        string token);

    // DELETE with Bearer token
    public static Task<int> DeleteAsync(
        this HttpClient httpClient,
        string url,
        string token);
}

MultipartFormDataRequest

Container for multipart form data uploads.

public class MultipartFormDataRequest
{
    public List<MultipartField> Fields { get; set; }
    public List<MultipartFile> Files { get; set; }
}

public class MultipartField
{
    public string Name { get; set; }
    public string Value { get; set; }
}

public class MultipartFile
{
    public string FieldName { get; set; }      // Default: "file"
    public string FileName { get; set; }       // e.g., "Token.sol"
    public string Content { get; set; }        // File content as string
    public string ContentType { get; set; }    // Default: "text/plain"
}

Used By (Consumers)

Nethereum.Beaconchain - Beacon chain API client
Nethereum.DataServices - Data service integrations (Sourcify, 4byte.directory)
Nethereum.Consensus.LightClient - Light client API communication

Dependencies

None (foundational package)

Important Notes

Response Size Cap

GetAsync, PostAsync, PutAsync, DeleteAsync and PostMultipartAsync send with ResponseHeadersRead and read each response body, successful or not, through one bounded reader and decode it with the charset in the response Content-Type (UTF-8 when none is declared). A body larger than MaxResponseBytes (default RestHttpHelper.DefaultMaxResponseBytes, 32 MiB) throws HttpRequestException, from the declared Content-Length before reading, or while streaming when the length is not declared. DeleteAsync and the body of a non-success response are capped the same way: an over-cap error body throws HttpRequestException instead of the status exception. The public SendAsync returns the raw HttpResponseMessage and is not capped: its caller owns reading the body. Raise or lower the limit per instance:

var restHelper = new RestHttpHelper(new HttpClient()) { MaxResponseBytes = 1024 * 1024 };

try
{
    var data = await restHelper.GetAsync<MyData>("https://api.example.com/data");
}
catch (HttpRequestException)
{
}

Error Handling

All methods throw Exception on non-success HTTP status codes. The message format differs slightly by method: only GetAsync includes the response headers; PostAsync, PutAsync, DeleteAsync, and PostMultipartAsync omit them.

try
{
    var data = await restHelper.GetAsync<MyData>("https://api.example.com/data");
}
catch (Exception ex)
{
    // From GetAsync, ex.Message contains: "Error: {StatusCode}, {ResponseBody}, {Headers}"
    Console.WriteLine($"API error: {ex.Message}");
}

try
{
    var response = await restHelper.PostAsync<CreateUserResponse, CreateUserRequest>(
        "https://api.example.com/users", request);
}
catch (Exception ex)
{
    // From PostAsync/PutAsync/DeleteAsync/PostMultipartAsync, ex.Message contains:
    // "Error: {StatusCode}, {ResponseBody}" — no headers
    Console.WriteLine($"API error: {ex.Message}");
}

HttpClient Lifecycle

Best Practice: Reuse HttpClient instances to avoid socket exhaustion.

// WRONG - creates new HttpClient for every request
public Task<T> GetDataAsync<T>(string url)
{
    var helper = new RestHttpHelper(new HttpClient()); // Don't do this!
    return helper.GetAsync<T>(url);
}

// CORRECT - reuse HttpClient
private readonly IRestHttpHelper _restHelper;

public MyService()
{
    var httpClient = new HttpClient(); // Create once
    _restHelper = new RestHttpHelper(httpClient);
}

Even Better: Use HttpClientFactory in ASP.NET Core:

// Startup.cs or Program.cs
services.AddHttpClient();

// Your service
public class MyService
{
    private readonly IRestHttpHelper _restHelper;

    public MyService(IHttpClientFactory httpClientFactory)
    {
        var httpClient = httpClientFactory.CreateClient();
        _restHelper = new RestHttpHelper(httpClient);
    }
}

JSON Serialization

The package automatically uses the best serializer for your framework:

.NET 8+: System.Text.Json (faster, lower memory)
Older frameworks: Newtonsoft.Json (compatibility)

This is transparent - you don't need to change your code.

Case Sensitivity

HttpClientExtensions use case-insensitive JSON deserialization:

var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true
};

This allows matching API responses with different casing conventions.

Thread Safety

RestHttpHelper is thread-safe when using a shared HttpClient (which is thread-safe). You can safely use a single instance across multiple threads.

Additional Resources

License

This package is part of the Nethereum project and follows the same MIT license.

Overview​

Installation​

Dependencies​

Key Concepts​

IRestHttpHelper Interface​

RestHttpHelper Implementation​

HttpClient Extensions​

JSON Serialization Strategy​

Quick Start​

Usage Examples​

Example 1: Basic GET Request with Custom Headers​

Example 2: Dependency Injection Pattern (Real Example from BeaconApiClient)​

Example 3: 4byte.directory API Integration (Real Example)​

Example 4: Sourcify Contract Verification API (Real Example)​

Example 5: POST Request with Custom Object​

Example 6: PUT Request for Updates​

Example 7: DELETE Request​

Example 8: HttpClient Extension Methods with Bearer Auth (.NET 5+)​

Example 9: Multipart Form Data for File Uploads​

API Reference​

IRestHttpHelper​

RestHttpHelper​

HttpClientExtensions (.NET 5.0+)​

MultipartFormDataRequest​

Related Packages​

Used By (Consumers)​

Dependencies​

Important Notes​

Response Size Cap​

Error Handling​

HttpClient Lifecycle​

JSON Serialization​

Case Sensitivity​

Thread Safety​

Additional Resources​

License​

Overview

Installation

Dependencies

Key Concepts

IRestHttpHelper Interface

RestHttpHelper Implementation

HttpClient Extensions

JSON Serialization Strategy

Quick Start

Usage Examples

Example 1: Basic GET Request with Custom Headers

Example 2: Dependency Injection Pattern (Real Example from BeaconApiClient)

Example 3: 4byte.directory API Integration (Real Example)

Example 4: Sourcify Contract Verification API (Real Example)

Example 5: POST Request with Custom Object

Example 6: PUT Request for Updates

Example 7: DELETE Request

Example 8: HttpClient Extension Methods with Bearer Auth (.NET 5+)

Example 9: Multipart Form Data for File Uploads

API Reference

IRestHttpHelper

RestHttpHelper

HttpClientExtensions (.NET 5.0+)

MultipartFormDataRequest

Related Packages

Used By (Consumers)

Dependencies

Important Notes

Response Size Cap

Error Handling

HttpClient Lifecycle

JSON Serialization

Case Sensitivity

Thread Safety

Additional Resources

License