NginxApiClient.SystemTextJson 1.0.4

NginxApiClient

A comprehensive C# client library for the NGINX Proxy Manager REST API.

Features

• Full API coverage — all 11 NPM resource groups (proxy hosts, certificates, redirection hosts, dead hosts, streams, access lists, users, settings, audit log, reports)
• Multi-target — supports .NET Framework 4.8 through .NET 9 via sub-package architecture
• Async-first — all methods are async with CancellationToken support
• Transparent authentication — JWT token lifecycle managed automatically
• Strongly-typed — typed request/response models with IntelliSense
• Testable — INginxProxyManagerClient interface for easy mocking
• DI-ready — IServiceCollection extension methods for ASP.NET Core

Installation

Modern .NET (.NET 8 / .NET 9)

dotnet add package NginxApiClient
dotnet add package NginxApiClient.SystemTextJson

.NET Framework 4.8

Install-Package NginxApiClient
Install-Package NginxApiClient.NewtonsoftJson

Quick Start

using NginxApiClient;
using NginxApiClient.SystemTextJson;

// Create client
var serializer = new SystemTextJsonSerializer();
var options = new NginxProxyManagerClientOptions
{
    BaseUrl = "http://localhost:81",
    Credentials = new NginxCredentials("admin@example.com", "changeme"),
};

// Authentication is handled automatically
var client = NginxProxyManagerClientFactory.Create(options, serializer);

// List all proxy hosts
var hosts = await client.ProxyHosts.ListAsync();
foreach (var host in hosts)
{
    Console.WriteLine($"{host.Id}: {string.Join(", ", host.DomainNames)} -> {host.ForwardHost}:{host.ForwardPort}");
}

ASP.NET Core DI Registration

// In Program.cs or Startup.cs
services.AddNginxApiClient(options =>
{
    options.BaseUrl = "http://npm:81";
    options.Credentials = new NginxCredentials("admin@example.com", "changeme");
});

// Inject into your services
public class MyService
{
    private readonly INginxProxyManagerClient _npmClient;

    public MyService(INginxProxyManagerClient npmClient)
    {
        _npmClient = npmClient;
    }

    public async Task CreateProxyHostAsync(string domain, string backendHost, int backendPort)
    {
        await _npmClient.ProxyHosts.CreateAsync(new CreateProxyHostRequest
        {
            DomainNames = new List<string> { domain },
            ForwardScheme = "http",
            ForwardHost = backendHost,
            ForwardPort = backendPort,
            SslForced = true,
            Http2Support = true,
        });
    }
}

Create a Proxy Host with SSL

var proxyHost = await client.ProxyHosts.CreateAsync(new CreateProxyHostRequest
{
    DomainNames = new List<string> { "app.example.com" },
    ForwardScheme = "http",
    ForwardHost = "192.168.1.100",
    ForwardPort = 8080,
    SslForced = true,
    HstsEnabled = true,
    Http2Support = true,
    BlockExploits = true,
    AllowWebsocketUpgrade = true,
    CertificateId = 5,  // ID of an existing certificate
});

Console.WriteLine($"Created proxy host {proxyHost.Id} for {string.Join(", ", proxyHost.DomainNames)}");

Certificate Management

// List certificates and check expiry
var certs = await client.Certificates.ListAsync();
foreach (var cert in certs)
{
    var daysUntilExpiry = (cert.ExpiresOn - DateTime.UtcNow).Days;
    Console.WriteLine($"{cert.NiceName}: expires in {daysUntilExpiry} days");

    if (daysUntilExpiry < 30)
    {
        await client.Certificates.RenewAsync(cert.Id);
        Console.WriteLine($"  -> Renewed!");
    }
}

// Provision a new Let's Encrypt certificate
var newCert = await client.Certificates.CreateAsync(new CreateCertificateRequest
{
    DomainNames = new List<string> { "new.example.com" },
    Provider = "letsencrypt",
    Meta = new CertificateMeta { LetsencryptEmail = "admin@example.com", LetsencryptAgree = true },
});

Error Handling

using NginxApiClient.Exceptions;

try
{
    var host = await client.ProxyHosts.GetAsync(999);
}
catch (NginxNotFoundException ex)
{
    Console.WriteLine($"Proxy host not found: {ex.ErrorDetail}");
}
catch (NginxAuthenticationException ex)
{
    Console.WriteLine($"Authentication failed: {ex.ErrorDetail}");
}
catch (NginxApiException ex)
{
    Console.WriteLine($"API error {ex.StatusCode}: {ex.ErrorDetail}");
}

Available Resource Clients

Package Architecture

Examples

See the examples/ folder for runnable console projects:

• BasicUsage — Authenticate, list/create/delete proxy hosts
• CertificateManagement — Certificate lifecycle automation
• LegacyFrameworkUsage — .NET Framework 4.8 example

License

MIT License - see LICENSE for details.