Client

Requisiti

Go 1.24 o più recente
Zero dipendenze esterne — l’SDK è costruito esclusivamente sulla libreria standard di Go
Una chiave API valida — richiedine una nella Dashboard di Square Cloud in My Account → Regenerate API/CLI KEY

Installazione

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

Il modulo fornisce due pacchetti:

Pacchetto	Percorso di import	Contenuto
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	Client HTTP, interfacce delle risorse, opzioni di richiesta, errori, stream SSE
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	Ogni tipo e struct di richiesta/risposta

Istanziare il client

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...) costruisce il client HTTP sottostante; rest.New(client) lo avvolge in rest.Rest, l’interfaccia che espone ogni risorsa. Usa sempre defer client.Close() per rilasciare le connessioni inattive.

Configurazione del client (`ConfigOpt`)

rest.NewClient accetta ConfigOpt opzionali dopo il token:

Opzione	Default	Descrizione
`rest.WithLogger(*slog.Logger)`	scartato	Logger strutturato per il debug di richieste/risposte
`rest.WithHTTPClient(*http.Client)`	timeout 30s	`*http.Client` personalizzato (proxy, transport, timeout)
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	URL base dell’API
`rest.WithUserAgent(string)`	default dell’SDK	Header `User-Agent` personalizzato

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

Moduli

rest.Rest incorpora un’interfaccia per ogni dominio di risorse, oltre ai metodi utente e di servizio documentati in questa pagina:

Interfaccia	Copertura	Documentazione
`Applications`	Gestione, upload, file, variabili d’ambiente, snapshot, deploy, rete, realtime	Gestire le applicazioni
`Databases`	Creazione, gestione, credenziali e snapshot	Database
`Workspaces`	Creazione, membri, applicazioni condivise	Workspace

Ottenere l’utente autenticato

api.SelfUser() restituisce un squarecloud.User con i dettagli dell’account e il piano attuale.

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)

Campo	Tipo	Descrizione
`ID`	`string`	ID utente (24 caratteri esadecimali)
`Name`	`string`	Nome visualizzato
`Email`	`string`	Email dell’account
`Locale`	`string`	Locale preferito, ad esempio `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`, `Memory{Limit, Available, Used}` (MB) e `Duration`
`CreatedAt`	`string`	Data di creazione dell’account

Elencare le tue applicazioni e i tuoi database

api.GetApplications() e api.GetDatabases() elencano tutto ciò che possiedi tramite l’endpoint /users/me, restituendo descrittori compatti squarecloud.UserApplication / squarecloud.UserDatabase:

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)
}

Per recuperare il record completo di una singola risorsa, usa GetApplication / GetDatabase — consulta Gestire le applicazioni e Database.

Elencare la cronologia degli snapshot (a livello di account)

api.UserSnapshots(scope) restituisce ogni snapshot che possiedi per un determinato dominio:

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

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

Consulta Snapshot per i dettagli sui payload degli snapshot.

Stato della piattaforma

api.ServiceStatus() espone lo stato di salute aggregato della piattaforma (gli stessi dati mostrati nella pagina di stato pubblica).

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

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

A differenza della maggior parte degli endpoint v2, questa route non avvolge il suo payload nella busta standard { status, code, response } — risponde direttamente con { status, message }.

Opzioni di richiesta

Ogni metodo accetta ...rest.RequestOpt finali per personalizzare la singola richiesta:

Opzione	Descrizione
`rest.WithContext(ctx)`	Allega un `context.Context` per cancellazione o scadenze
`rest.WithQueryParam(key, value)`	Aggiunge un parametro di query
`rest.WithHeader(key, value)`	Imposta un header della richiesta
`rest.WithToken(token)`	Sovrascrive il token di autenticazione solo per questa richiesta

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

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

Gestione degli errori

Qualsiasi risposta non-2xx viene restituita come *rest.APIError, che espone StatusCode, Code e Message. Estrailo con l’idiomatico 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
}

Due helper semplificano i controlli più comuni:

rest.ErrorCode(err) string — restituisce il codice di errore dell’API (oppure "" quando l’errore non è un *rest.APIError)
rest.IsRateLimit(err) bool — indica se l’errore corrisponde a uno dei codici di rate limit (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")
	}
}

I codici di errore sono gli stessi usati da @squarecloud/api-types — consulta la tabella completa dei codici nel riferimento dell’SDK JS.

Servizi

Runtimes

Piattaforma

Risoluzione dei problemi

CLI

SDKs

Changelog

Requisiti

Installazione

Istanziare il client

Configurazione del client (`ConfigOpt`)

Moduli

Ottenere l’utente autenticato

Elencare le tue applicazioni e i tuoi database

Elencare la cronologia degli snapshot (a livello di account)

Stato della piattaforma

Opzioni di richiesta

Gestione degli errori

​Requisiti

​Installazione

​Istanziare il client

​Configurazione del client (ConfigOpt)

​Moduli

​Ottenere l’utente autenticato

​Elencare le tue applicazioni e i tuoi database

​Elencare la cronologia degli snapshot (a livello di account)

​Stato della piattaforma

​Opzioni di richiesta

​Gestione degli errori

Requisiti

Installazione

Istanziare il client

Configurazione del client (`ConfigOpt`)

Moduli

Ottenere l’utente autenticato

Elencare le tue applicazioni e i tuoi database

Elencare la cronologia degli snapshot (a livello di account)

Stato della piattaforma

Opzioni di richiesta

Gestione degli errori