Go Module
Go SDK (noxaeapi-sdk-go)
Official idiomatic Go client module for NoxAeApi REST + WebSocket platform. Built with full context.Context cancellation, struct modeling, and automatic retries.
Idiomatic Go Design
Clean struct pointers, slice returns, and standard error handling idioms.
13 Core Modules
Complete coverage for players, economy, server, worlds, plugins, LuckPerms, NoxAuth, skills, and Velocity.
Context Cancellation
First-class context.Context support across all API calls for timeouts and cancellation.
Automatic Retries
Built-in exponential backoff with configurable RetryOptions for resilient networking.
Installation
Get the module using go get:
Terminal
go get github.com/NoxlyDev/noxaeapi-sdk-goBasic Usage
Instantiate the Client struct with your server base URL and API key:
main.go
package main
import (
"context"
"fmt"
"log"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
client, err := noxaeapi.NewClient("http://localhost:8080", "your-api-key")
if err != nil {
log.Fatalf("Failed to initialize client: %v", err)
}
ctx := context.Background()
// Access any of the 13 core modules
players, err := client.Players().List(ctx)
if err != nil {
log.Fatalf("Error fetching players: %v", err)
}
if len(players) > 0 {
balance, err := client.Economy().GetBalance(ctx, players[0].UUID)
if err == nil {
fmt.Printf("Player %s balance: $%.2f\n", players[0].Name, balance)
}
}
_ = client.Server().Broadcast(ctx, "Hello from the Go SDK!")
}Loading from Environment
Initialize the client automatically from process environment variables without hardcoding secrets:
env_example.go
package main
import (
"context"
"log"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
// Reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from os.Getenv
client, err := noxaeapi.NewClientFromEnv()
if err != nil {
log.Fatalf("Failed to initialize client from environment: %v", err)
}
_ = client
}Environment Convention
noxaeapi.NewClientFromEnv() reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from os.Getenv.
Realtime WebSocket Streams
Stream live Minecraft server console logs and game events over WebSocket connections:
realtime.go
package main
import (
"context"
"fmt"
"log"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
client, _ := noxaeapi.NewClientFromEnv()
// Stream live console logs over WebSocket
consoleWs, err := client.ConnectConsole(context.Background())
if err != nil {
log.Fatalf("Console connection failed: %v", err)
}
defer consoleWs.Close()
for line := range consoleWs.Lines() {
fmt.Printf("[Console] %s\n", line)
}
}WebSocket Client
WebSocket streaming uses gorilla/websocket with thread-safe channel handlers and automatic reconnect.
Error Handling & Exceptions
All API methods return error values implementing the *NoxAeApiError type:
errors.go
package main
import (
"context"
"errors"
"fmt"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
client, _ := noxaeapi.NewClientFromEnv()
err := client.Server().Restart(context.Background())
if err != nil {
var apiErr *noxaeapi.NoxAeApiError
if errors.As(err, &apiErr) {
switch apiErr.StatusCode {
case 401:
fmt.Println("Unauthorized API key")
case 403:
fmt.Println("Forbidden endpoint")
case 404:
fmt.Println("Resource not found")
default:
fmt.Printf("API error [%d]: %s\n", apiErr.StatusCode, apiErr.Message)
}
}
}
}Error Struct Fields
NoxAeApiError (401)401 — API key is missing or rejectedNoxAeApiError (403)403 — API key is valid but lacks permissions for this endpointNoxAeApiError (404)404 — Target player, world, or resource does not existNoxAeApiError (429)429 — Rate limit exceeded (auto-retried when retry is enabled)NoxAeApiError (5xx)5xx — Minecraft server internal error (auto-retried)Network/Timeout ErrorConnection refused, DNS failure, or socket timeoutClient Configuration
Customize timeouts, retry strategies with exponential backoff, and custom request headers:
config_example.go
package main
import (
"time"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
client, _ := noxaeapi.NewClient(
"https://mc.example.com",
"your-api-key",
noxaeapi.WithTimeout(10*time.Second),
noxaeapi.WithRetryOptions(noxaeapi.RetryOptions{
Attempts: 3,
BaseDelay: 300 * time.Millisecond,
MaxDelay: 5 * time.Second,
}),
)
_ = client
}Modules Catalog (13)
Browse all 13 sub-modules available under the Client instance:
| Method | Return Type | Description | REST Spec |
|---|---|---|---|
List(ctx) | ([]OnlinePlayer, error) | Get a slice of all currently online players with locations, health, and metadata. | Endpoint |
ListAll(ctx) | ([]OfflinePlayer, error) | Get every player the server has ever seen (online + offline). | Endpoint |
Get(ctx, uuid) | (*PlayerDetail, error) | Get in-depth attributes and real-time state for a specific player by UUID. | Endpoint |
GetInventory(ctx, playerUuid, worldUuid) | ([]InventorySlot, error) | Inspect a player's armor, hotbar, offhand, and storage inventory slots. | Endpoint |
Kick(ctx, uuid, reason)ADMIN | error | Disconnect an online player with an optional kick reason. | Endpoint |
Ban(ctx, uuid, reason, expiry)ADMIN | error | Ban a player UUID with optional reason and expiration time. | Endpoint |
Unban(ctx, uuid)ADMIN | error | Remove a player ban entry by UUID. | Endpoint |
Teleport(ctx, uuid, target) | error | Teleport player to target coordinates in a specified world dimension. | Endpoint |
SetGamemode(ctx, uuid, gamemode)ADMIN | error | Update active gamemode (Survival, Creative, Adventure, Spectator). | Endpoint |
GetStats(ctx, uuid) | (*PlayerStats, error) | Fetch gameplay statistics (kills, deaths, playtime, distance walked). | Endpoint |
Resolve(ctx, player) | (*PlayerProfile, error) | Resolve a player UUID or username to a complete PlayerProfile struct pointer. | Endpoint |
GetPlayerProfile(ctx, player) | (*PlayerProfile, error) | Fetch detailed profile attributes for a player by UUID or username. | Endpoint |
GetPlayerProfiles(ctx, players) | ([]PlayerProfile, error) | Batch resolve multiple player UUIDs or usernames in a single API call. | Endpoint |
Usage Example
examples/players_example.go
package main
import (
"context"
"fmt"
"log"
"time"
"github.com/NoxlyDev/noxaeapi-sdk-go"
)
func main() {
client, err := noxaeapi.NewClientFromEnv()
if err != nil {
log.Fatalf("failed to init client: %v", err)
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// List online players
players, err := client.Players.List(ctx)
if err != nil {
log.Fatalf("failed to list players: %v", err)
}
fmt.Printf("Online players: %d\n", len(players))
// Resolve player profile
profile, err := client.Players.Resolve(ctx, "Notch")
if err == nil {
fmt.Printf("Resolved UUID: %s\n", profile.UUID)
}
}See Also & Integrations
Explore alternative client packages and complete endpoint specifications: