Locaweb Servidores SDK .NET

Locaweb Servidores API Client SDK for .NET projects

CI/CD

Build status	Last commit	Tests	Coverage	Code Smells	LoC

Code Quality (main branch)

Installation

Github Releases

Download the latest zip file from the Release page.

Nuget package manager

Package	Version	Downloads
LocawebServidores

dotnet add package LocawebServidores

Targets netstandard2.0 and netstandard2.1, so it runs on .NET Framework 4.6.1+, .NET Core and .NET 5+. The only dependency is System.Text.Json.

Features

Implements the Locaweb API de Servidores (https://api-servidores.locaweb.com.br/v1), a JSON:API service for managing and monitoring Cloud Server Pro, VPS and dedicated servers.

Area	Client property	Endpoints
Cloud Server Pro	`client.CloudServers`	list, details, status (sparse fieldset + available actions), change nickname, installation images
VPS	`client.VpsServers`	list, details, status
Dedicated servers	`client.DedicatedServers`	list, details, status, change nickname
Actions (reboot, …)	`client.Actions`	list, details, create, reboot, wait for completion
IPs	`client.Ips`	list, details
Firewalls	`client.Firewalls`	list, details, create, delete
Snapshots	`client.Snapshots`	list, details, create, delete, snapshot actions (list/details/create/wait)
Scheduled snapshots	`client.ScheduledSnapshots`	list, details, create, delete
Custom templates	`client.CustomTemplates`	list, details, create, delete
Scalability	`client.Scalability`	scale windows (list/create/update/delete/stop), event triggers (list/update), plans, scale info
Anything else	`client.Connection`	raw `GET`/`POST`/`PUT`/`DELETE` with the same auth, serialization and error mapping

SDK conventions:

Every call is asynchronous, accepts a CancellationToken, and never blocks.
Responses keep the JSON:API envelope: Id, Type, typed Attributes, plus raw Meta, Links and Relationships. Attributes the SDK does not model are preserved in AdditionalAttributes and readable through GetAttribute<T>("name").
Non-success responses become typed exceptions with the parsed JSON:API errors array.
Request bodies follow the JSON:API shape { "data": { "type": ..., "attributes": {...} } } with the application/vnd.api+json media type.
Works with IHttpClientFactory: pass your own HttpClient and the SDK never mutates it.

Usage

Creating the client

Generate an API token in the API area of the Locaweb Cloud/Dedicated servers panel.

using LocawebServidores;

// Simplest form: the client owns its HttpClient.
using var client = new LocawebServidoresClient("your-api-token");

// Full options.
using var configured = new LocawebServidoresClient(
    new LocawebServidoresClientOptions
    {
        ApiToken = "your-api-token",
        Locale = "pt-BR", // API messages in Portuguese (default is English)
        Timeout = TimeSpan.FromSeconds(30),
    }
);

With dependency injection / IHttpClientFactory:

services.AddHttpClient<ILocawebServidoresClient, LocawebServidoresClient>(
    (httpClient, _) =>
        new LocawebServidoresClient(
            httpClient,
            new LocawebServidoresClientOptions { ApiToken = configuration["Locaweb:ApiToken"] }
        )
);

Server management

using LocawebServidores.Models;
using LocawebServidores.Models.Requests;

// List cloud servers (page 2, 50 per page, newest first).
var servers = await client.CloudServers.ListAsync(
    new RequestOptions().WithPage(2, 50).WithSort("-created_at")
);
foreach (var server in servers.Items)
{
    Console.WriteLine($"{server.Id}: {server.Attributes?.Nickname} ({server.Attributes?.PowerState})");
}

// Details of one server, including attributes the SDK does not model.
var details = await client.CloudServers.GetAsync("srv-001");
var operatingSystem = details.Attributes?.GetAttribute<string>("os");

// Change the nickname (also available for dedicated servers).
await client.CloudServers.UpdateNicknameAsync("srv-001", "web-01");

// VPS and dedicated servers.
var vps = await client.VpsServers.ListAsync();
var dedicated = await client.DedicatedServers.ListAsync();

// Firewall rules.
var rule = await client.Firewalls.CreateAsync(
    "srv-001",
    new CreateFirewallRuleRequest(FirewallProtocols.Tcp, source: "0.0.0.0/0", initialPort: 443)
);
await client.Firewalls.DeleteAsync("srv-001", rule.Id!);

// Snapshots and schedules.
var snapshot = await client.Snapshots.CreateAsync("srv-001", new CreateSnapshotRequest("before-upgrade"));
await client.ScheduledSnapshots.CreateAsync(
    "srv-001",
    new CreateScheduledSnapshotRequest(frequency: "weekly", time: "03:00", dayOfWeek: "sunday", retention: 4)
);

// Custom templates.
await client.CustomTemplates.CreateAsync("srv-001", new CreateCustomTemplateRequest("golden-image"));

// Scalability: scale up to a bigger plan for six hours.
var plans = await client.Scalability.ListPlansAsync("srv-001");
var start = DateTimeOffset.UtcNow.AddHours(1);
await client.Scalability.CreateScaleWindowAsync(
    "srv-001",
    new ScaleWindowRequest(plans.Items[0].Id!, start, start.AddHours(6))
);

Server monitoring

// Lightweight status check: requests only power_state and status (fields[servers]=...)
// and reads the actions the API currently allows from meta.actions.
var status = await client.CloudServers.GetStatusAsync("srv-001");
Console.WriteLine($"{status.Status} / {status.PowerState} / can: {string.Join(", ", status.AvailableActions)}");

// Reboot and wait for the asynchronous action to finish.
var action = await client.Actions.RebootAsync("srv-001");
var finished = await client.Actions.WaitForCompletionAsync(
    "srv-001",
    action.Id!,
    isCompleted: a => a.Attributes?.Status is "completed" or "failed",
    pollInterval: TimeSpan.FromSeconds(5),
    timeout: TimeSpan.FromMinutes(10)
);

// Action history of a server.
var history = await client.Actions.ListAsync("srv-001");

// Scalability monitoring: current status and CPU/memory triggers.
var scaleInfo = await client.Scalability.GetScaleInfoAsync("srv-001");
var triggers = await client.Scalability.ListEventTriggersAsync("srv-001");
await client.Scalability.UpdateEventTriggerAsync(
    "srv-001",
    triggers.Items[0].Id!,
    new UpdateEventTriggerRequest { Threshold = 85, Enabled = true }
);

Error handling

using LocawebServidores.Exceptions;

try
{
    await client.CloudServers.GetAsync("does-not-exist");
}
catch (LocawebServidoresNotFoundException) { /* 404 */ }
catch (LocawebServidoresAuthenticationException) { /* 401 / 403: check the token */ }
catch (LocawebServidoresValidationException ex) // 400 / 422
{
    foreach (var error in ex.Errors)
    {
        Console.WriteLine($"{error.Source?.Pointer}: {error.Detail}");
    }
}
catch (LocawebServidoresRateLimitException ex) // 429
{
    await Task.Delay(ex.RetryAfter ?? TimeSpan.FromSeconds(10));
}
catch (LocawebServidoresServerErrorException) { /* 5xx: retry later */ }
catch (LocawebServidoresTimeoutException) { /* HTTP timeout or WaitForCompletionAsync timeout */ }
catch (LocawebServidoresApiException ex) { /* any other non-success status */ Console.WriteLine(ex.StatusCode); }
catch (LocawebServidoresException) { /* transport failure or unparsable payload */ }

Every API exception exposes StatusCode, ResponseContent, ResponseHeaders and the parsed JSON:API Errors. Cancellation through your own CancellationToken surfaces as OperationCanceledException, as usual.

Calling endpoints the SDK does not model

using LocawebServidores.JsonApi;
using System.Text.Json;

var response = await client.Connection.SendAsync(HttpMethod.Get, "cloud/servers/srv-001/network_interfaces");
var document = response.Deserialize<JsonApiDocument<JsonElement>>();

// Typed variant.
var interfaces = await client.Connection.GetAsync<ResourceCollection<MyInterfaceModel>>(
    "cloud/servers/srv-001/network_interfaces",
    new RequestOptions().WithFields("network_interfaces", "mac", "ip")
);

Request models accept extra attributes too, for fields the SDK does not know about:

var request = new CreateActionRequest("reinstall");
request.SetAttribute("image_id", "img-123");
await client.Actions.CreateAsync("srv-001", request);

Authentication header

The token is sent in the X-Auth-Token header, the convention used by Locaweb’s public APIs. If your account requires a different header, change it without touching any other code:

var options = new LocawebServidoresClientOptions
{
    ApiToken = "your-api-token",
    AuthenticationHeaderName = "Authorization",
    AuthenticationScheme = "Bearer", // sends "Authorization: Bearer your-api-token"
};

Tests

dotnet test

Unit tests (Tests/LocawebServidores.UnitTests) mock the HTTP layer and cover request building, authentication, serialization, every resource and the error mapping.
Integration tests (Tests/LocawebServidores.IntegrationTests) run the SDK through a real HttpClient against an in-process JSON:API server, with no network access required.
Live tests in the same project call the real API and are skipped unless the LOCAWEB_API_TOKEN environment variable is set (optionally LOCAWEB_AUTH_HEADER and LOCAWEB_AUTH_SCHEME to override the authentication header). They only read data.