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
| 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)
}
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)
}
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
}
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")
}
}
@squarecloud/api-types — consultez la table complète des codes dans la référence du SDK JS.
