Client

Voraussetzungen

Go 1.24 oder neuer
Null externe Abhängigkeiten — das SDK baut ausschließlich auf der Go-Standardbibliothek auf
Ein gültiger API-Schlüssel — fordere einen im Square Cloud Dashboard unter My Account → Regenerate API/CLI KEY an

Installation

go get github.com/squarecloudofc/sdk-api-go/v2

Das Modul liefert zwei Pakete:

Paket	Importpfad	Inhalt
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	HTTP-Client, Ressourcen-Schnittstellen, Request-Optionen, Fehler, SSE-Stream
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	Jeder Request-/Response-Typ und jedes Struct

Instanziierung des Clients

package main

import (
	"fmt"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v2/rest"
)

func main() {
	client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
	defer client.Close()

	api := rest.New(client)

	user, err := api.SelfUser()
	if err != nil {
		panic(err)
	}
	fmt.Println(user.Name)
}

rest.NewClient(token, opts...) baut den zugrunde liegenden HTTP-Client; rest.New(client) verpackt ihn in rest.Rest, die Schnittstelle, die jede Ressource bereitstellt. Rufe stets defer client.Close() auf, um inaktive Verbindungen freizugeben.

Client-Konfiguration (`ConfigOpt`)

rest.NewClient akzeptiert nach dem Token optionale ConfigOpts:

Option	Standard	Beschreibung
`rest.WithLogger(*slog.Logger)`	verworfen	Strukturierter Logger für Request-/Response-Debugging
`rest.WithHTTPClient(*http.Client)`	30s Timeout	Eigener `*http.Client` (Proxys, Transports, Timeouts)
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	Basis-URL der API
`rest.WithUserAgent(string)`	SDK-Standard	Eigener `User-Agent`-Header

client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

Module

rest.Rest bettet eine Schnittstelle pro Ressourcen-Domäne ein, dazu die auf dieser Seite dokumentierten Benutzer- und Service-Methoden:

Schnittstelle	Abdeckung	Dokumentation
`Applications`	Verwalten, Upload, Dateien, Envs, Snapshots, Deploys, Netzwerk, Realtime	Anwendungen verwalten
`Databases`	Erstellen, Verwalten, Zugangsdaten und Snapshots	Datenbanken
`Workspaces`	Erstellen, Mitglieder, geteilte Anwendungen	Workspaces

Den authentifizierten Benutzer abrufen

api.SelfUser() gibt einen squarecloud.User mit den Kontodetails und dem aktuellen Plan zurück.

user, err := api.SelfUser()
if err != nil {
	panic(err)
}

fmt.Println(user.ID)       // "abcdef0123456789abcdef01"
fmt.Println(user.Name)     // "John Doe"
fmt.Println(user.Email)    // "john@example.com"
fmt.Println(user.Locale)   // "en-US"
fmt.Println(user.Plan.Name)             // e.g. "standard"
fmt.Println(user.Plan.Duration)         // plan duration, e.g. "monthly"
fmt.Println(user.Plan.Memory.Limit)     // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used)      // MB
fmt.Println(user.CreatedAt)

Feld	Typ	Beschreibung
`ID`	`string`	Benutzer-ID (24 Hex-Zeichen)
`Name`	`string`	Anzeigename
`Email`	`string`	Konto-E-Mail
`Locale`	`string`	Bevorzugte Locale, z. B. `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`, `Memory{Limit, Available, Used}` (MB) und `Duration`
`CreatedAt`	`string`	Erstellungsdatum des Kontos

Deine Anwendungen und Datenbanken auflisten

api.GetApplications() und api.GetDatabases() listen über den Endpoint /users/me alles auf, was dir gehört, und geben kompakte squarecloud.UserApplication- / squarecloud.UserDatabase-Deskriptoren zurück:

apps, err := api.GetApplications()
if err != nil {
	panic(err)
}
for _, app := range apps {
	fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}

dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}
for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}

Um den vollständigen Datensatz einer einzelnen Ressource abzurufen, verwende GetApplication / GetDatabase — siehe Anwendungen verwalten und Datenbanken.

Snapshot-Verlauf auflisten (kontoweit)

api.UserSnapshots(scope) gibt jeden Snapshot zurück, den du in einer gegebenen Domäne besitzt:

appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}

Siehe Snapshots für Details zu Snapshot-Payloads.

Plattformstatus

api.ServiceStatus() stellt den aggregierten Plattformzustand bereit (dieselben Daten, die auf der öffentlichen Statusseite angezeigt werden).

status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // human-readable summary

Anders als die meisten v2-Endpoints kapselt diese Route ihr Payload nicht in den Standard-Envelope { status, code, response } — sie antwortet direkt mit { status, message }.

Request-Optionen

Jede Methode akzeptiert am Ende ...rest.RequestOpts, um den einzelnen Request anzupassen:

Option	Beschreibung
`rest.WithContext(ctx)`	Hängt einen `context.Context` für Abbruch oder Deadlines an
`rest.WithQueryParam(key, value)`	Fügt einen Query-Parameter hinzu
`rest.WithHeader(key, value)`	Setzt einen Request-Header
`rest.WithToken(token)`	Überschreibt das Authentifizierungs-Token nur für diesen Request

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
	panic(err)
}

Fehlerbehandlung

Jede Nicht-2xx-Antwort wird als *rest.APIError zurückgegeben, der StatusCode, Code und Message bereitstellt. Entpacke ihn mit dem idiomatischen errors.As:

app, err := api.GetApplication("invalid-id")
if err != nil {
	var apiErr *rest.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode) // e.g. 404
		fmt.Println(apiErr.Code)       // e.g. "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}

Zwei Helfer vereinfachen häufige Prüfungen:

rest.ErrorCode(err) string — gibt den API-Fehlercode zurück (oder "", wenn der Fehler kein *rest.APIError ist)
rest.IsRateLimit(err) bool — meldet, ob der Fehler einer der Rate-Limit-Codes ist (KEEP_CALM, RATE_LIMIT, RATE_LIMIT_EXCEEDED, RATELIMIT, DELAY_NOW)

if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// retry...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("application does not exist")
	case "ACCESS_DENIED":
		fmt.Println("invalid API key")
	}
}

Die Fehlercodes sind dieselben, die @squarecloud/api-types verwendet — siehe die vollständige Code-Tabelle in der JS-SDK-Referenz.

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

Voraussetzungen

Installation

Instanziierung des Clients

Client-Konfiguration (`ConfigOpt`)

Module

Den authentifizierten Benutzer abrufen

Deine Anwendungen und Datenbanken auflisten

Snapshot-Verlauf auflisten (kontoweit)

Plattformstatus

Request-Optionen

Fehlerbehandlung

​Voraussetzungen

​Installation

​Instanziierung des Clients

​Client-Konfiguration (ConfigOpt)

​Module

​Den authentifizierten Benutzer abrufen

​Deine Anwendungen und Datenbanken auflisten

​Snapshot-Verlauf auflisten (kontoweit)

​Plattformstatus

​Request-Optionen

​Fehlerbehandlung

Voraussetzungen

Installation

Instanziierung des Clients

Client-Konfiguration (`ConfigOpt`)

Module

Den authentifizierten Benutzer abrufen

Deine Anwendungen und Datenbanken auflisten

Snapshot-Verlauf auflisten (kontoweit)

Plattformstatus

Request-Optionen

Fehlerbehandlung