Client

Prérequis

Go 1.24 ou une version plus récente
Zéro dépendance externe — le SDK repose uniquement sur la bibliothèque standard de Go
Une clé d’API valide — demandez-en une sur le tableau de bord Square Cloud sous My Account → Regenerate API/CLI KEY

Installation

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

Le module fournit deux packages :

Package	Chemin d’import	Contenu
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	Client HTTP, interfaces de ressources, options de requête, erreurs, flux SSE
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	Tous les types et structs de requête/réponse

Instanciation du 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...) construit le client HTTP sous-jacent ; rest.New(client) l’enveloppe dans rest.Rest, l’interface qui expose chaque ressource. Faites toujours defer client.Close() pour libérer les connexions inactives.

Configuration du client (`ConfigOpt`)

rest.NewClient accepte des ConfigOpts optionnels après le token :

Option	Défaut	Description
`rest.WithLogger(*slog.Logger)`	ignoré	Logger structuré pour le débogage des requêtes/réponses
`rest.WithHTTPClient(*http.Client)`	timeout de 30s	`*http.Client` personnalisé (proxys, transports, timeouts)
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	URL de base de l’API
`rest.WithUserAgent(string)`	défaut du SDK	En-tête `User-Agent` personnalisé

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

Modules

rest.Rest embarque une interface par domaine de ressource, plus les méthodes utilisateur et service documentées sur cette page :

Interface	Couverture	Documentation
`Applications`	Gestion, envoi, fichiers, variables d’environnement, snapshots, deploys, réseau, temps réel	Gestion des applications
`Databases`	Création, gestion, identifiants et snapshots	Bases de données
`Workspaces`	Création, membres, applications partagées	Workspaces

Récupérer l’utilisateur authentifié

api.SelfUser() renvoie un squarecloud.User contenant les détails du compte et le plan actuel.

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)         // durée du plan, ex. "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)

Champ	Type	Description
`ID`	`string`	ID de l’utilisateur (24 caractères hexadécimaux)
`Name`	`string`	Nom d’affichage
`Email`	`string`	Email du compte
`Locale`	`string`	Locale préférée, ex. `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`, `Memory{Limit, Available, Used}` (Mo) et `Duration`
`CreatedAt`	`string`	Date de création du compte

Lister vos applications et bases de données

api.GetApplications() et api.GetDatabases() listent tout ce que vous possédez via l’endpoint /users/me, en renvoyant des descripteurs compacts 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)
}

Pour récupérer l’enregistrement complet d’une seule ressource, utilisez GetApplication / GetDatabase — consultez Gestion des applications et Bases de données.

Lister l’historique des snapshots (à l’échelle du compte)

api.UserSnapshots(scope) renvoie tous les snapshots que vous possédez pour un domaine donné :

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

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

Consultez Snapshots pour plus de détails sur les charges utiles des snapshots.

État de la plateforme

api.ServiceStatus() expose l’état de santé agrégé de la plateforme (les mêmes données affichées sur la page de statut publique).

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

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // résumé lisible par un humain

Contrairement à la plupart des endpoints v2, cette route n’enveloppe pas sa charge utile dans l’enveloppe standard { status, code, response } — elle répond directement avec { status, message }.

Options de requête

Chaque méthode accepte des ...rest.RequestOpts en fin d’appel pour personnaliser la requête individuelle :

Option	Description
`rest.WithContext(ctx)`	Attache un `context.Context` pour l’annulation ou les délais limites
`rest.WithQueryParam(key, value)`	Ajoute un paramètre de requête
`rest.WithHeader(key, value)`	Définit un en-tête de requête
`rest.WithToken(token)`	Remplace le token d’authentification pour cette requête uniquement

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

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

Gestion des erreurs

Toute réponse non-2xx est renvoyée sous forme de *rest.APIError exposant StatusCode, Code et Message. Dépliez-la avec l’idiomatique 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
}

Deux helpers simplifient les vérifications courantes :

rest.ErrorCode(err) string — renvoie le code d’erreur de l’API (ou "" lorsque l’erreur n’est pas une *rest.APIError)
rest.IsRateLimit(err) bool — indique si l’erreur correspond à l’un des codes de limitation de débit (KEEP_CALM, RATE_LIMIT, RATE_LIMIT_EXCEEDED, RATELIMIT, DELAY_NOW)

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

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

Les codes d’erreur sont les mêmes que ceux utilisés par @squarecloud/api-types — consultez la table complète des codes dans la référence du SDK JS.

Services

Runtimes

Plateforme

Dépannage

CLI

SDKs

Changelog

Prérequis

Installation

Instanciation du client

Configuration du client (`ConfigOpt`)

Modules

Récupérer l’utilisateur authentifié

Lister vos applications et bases de données

Lister l’historique des snapshots (à l’échelle du compte)

État de la plateforme

Options de requête

Gestion des erreurs

​Prérequis

​Installation

​Instanciation du client

​Configuration du client (ConfigOpt)

​Modules

​Récupérer l’utilisateur authentifié

​Lister vos applications et bases de données

​Lister l’historique des snapshots (à l’échelle du compte)

​État de la plateforme

​Options de requête

​Gestion des erreurs

Prérequis

Installation

Instanciation du client

Configuration du client (`ConfigOpt`)

Modules

Récupérer l’utilisateur authentifié

Lister vos applications et bases de données

Lister l’historique des snapshots (à l’échelle du compte)

État de la plateforme

Options de requête

Gestion des erreurs