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)

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

// Service class using dependency injection
public class BeaconApiClient
{
    private readonly IRestHttpHelper _restHelper;
    public string BaseUrl { get; }

    // Constructor with HttpClient
    public BeaconApiClient(string baseUrl, HttpClient httpClient = null)
    {
        BaseUrl = baseUrl.TrimEnd('/');
        _restHelper = new RestHttpHelper(httpClient ?? new HttpClient());
    }

    // Constructor with IRestHttpHelper (for testing)
    public BeaconApiClient(string baseUrl, IRestHttpHelper restHelper)
    {
        BaseUrl = baseUrl.TrimEnd('/');
        _restHelper = restHelper;
    }

    // Example method
    public async Task<BootstrapResponse> GetBootstrapAsync(string blockRoot)
    {
        var url = $"{BaseUrl}/eth/v1/beacon/light_client/bootstrap/{blockRoot}";
        return await _restHelper.GetAsync<BootstrapResponse>(url);
    }
}

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.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

Concrete implementation of IRestHttpHelper.

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

    // 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"
}

Related Packages

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

Error Handling

All methods throw Exception on non-success HTTP status codes:

try
{
    var data = await restHelper.GetAsync<MyData>("https://api.example.com/data");
}
catch (Exception ex)
{
    // ex.Message contains: "Error: {StatusCode}, {ResponseBody}, {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.

Nethereum.Util.Rest

Generic REST client abstraction and implementation for HTTP API interactions with JSON serialization support.

Overview

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)

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

// Service class using dependency injection
public class BeaconApiClient
{
    private readonly IRestHttpHelper _restHelper;
    public string BaseUrl { get; }

    // Constructor with HttpClient
    public BeaconApiClient(string baseUrl, HttpClient httpClient = null)
    {
        BaseUrl = baseUrl.TrimEnd('/');
        _restHelper = new RestHttpHelper(httpClient ?? new HttpClient());
    }

    // Constructor with IRestHttpHelper (for testing)
    public BeaconApiClient(string baseUrl, IRestHttpHelper restHelper)
    {
        BaseUrl = baseUrl.TrimEnd('/');
        _restHelper = restHelper;
    }

    // Example method
    public async Task<BootstrapResponse> GetBootstrapAsync(string blockRoot)
    {
        var url = $"{BaseUrl}/eth/v1/beacon/light_client/bootstrap/{blockRoot}";
        return await _restHelper.GetAsync<BootstrapResponse>(url);
    }
}

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.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

Concrete implementation of IRestHttpHelper.

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

    // 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"
}

Related Packages

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

Error Handling

All methods throw Exception on non-success HTTP status codes:

try
{
    var data = await restHelper.GetAsync<MyData>("https://api.example.com/data");
}
catch (Exception ex)
{
    // ex.Message contains: "Error: {StatusCode}, {ResponseBody}, {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.

juanblanco/Nethereum.Util.Restv5.8.0

Get Started

Readme

Nethereum.Util.Rest

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

Error Handling

HttpClient Lifecycle

JSON Serialization

Case Sensitivity

Thread Safety

Additional Resources

License

juanblanco/Nethereum.Util.Restv5.8.0

Get Started

Readme

Nethereum.Util.Rest

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

Error Handling

HttpClient Lifecycle

JSON Serialization

Case Sensitivity

Thread Safety

Additional Resources

License