Requisitos
- Go 1.24 o más reciente
- Cero dependencias externas — el SDK está construido únicamente sobre la biblioteca estándar de Go
- Una clave de API válida — solicita una en el Panel de Square Cloud en My Account → Regenerate API/CLI KEY
Instalación
go get github.com/squarecloudofc/sdk-api-go/v2
| Paquete | Ruta de import | Contenido |
|---|
rest | github.com/squarecloudofc/sdk-api-go/v2/rest | Cliente HTTP, interfaces de recursos, opciones de solicitud, errores, stream SSE |
squarecloud | github.com/squarecloudofc/sdk-api-go/v2/squarecloud | Todos los tipos y structs de solicitud/respuesta |
Instanciar el cliente
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...) construye el cliente HTTP subyacente; rest.New(client) lo envuelve en rest.Rest, la interfaz que expone cada recurso. Usa siempre defer client.Close() para liberar las conexiones inactivas.
Configuración del cliente (ConfigOpt)
rest.NewClient acepta ConfigOpts opcionales después del token:
| Opción | Predeterminado | Descripción |
|---|
rest.WithLogger(*slog.Logger) | descartado | Logger estructurado para depurar solicitudes/respuestas |
rest.WithHTTPClient(*http.Client) | timeout de 30s | *http.Client personalizado (proxies, transports, timeouts) |
rest.WithURL(string) | https://api.squarecloud.app/v2 | URL base de la API |
rest.WithUserAgent(string) | valor predeterminado del SDK | Header User-Agent personalizado |
client := rest.NewClient(
os.Getenv("SQUARECLOUD_API_KEY"),
rest.WithLogger(slog.Default()),
rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)
Módulos
rest.Rest embebe una interfaz por dominio de recursos, además de los métodos de usuario y servicio documentados en esta página:
| Interfaz | Cobertura | Documentación |
|---|
Applications | Gestión, subida, archivos, variables de entorno, snapshots, deploys, red, tiempo real | Gestionar aplicaciones |
Databases | Creación, gestión, credenciales y snapshots | Bases de datos |
Workspaces | Creación, miembros, aplicaciones compartidas | Workspaces |
Obtener el usuario autenticado
api.SelfUser() devuelve un squarecloud.User con los detalles de la cuenta y el plan actual.
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) // duración del plan, 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 | Descripción |
|---|
ID | string | ID del usuario (24 caracteres hex) |
Name | string | Nombre visible |
Email | string | Email de la cuenta |
Locale | string | Locale preferido, e.g. "en-US" |
Plan | squarecloud.UserPlan | Name, Memory{Limit, Available, Used} (MB) y Duration |
CreatedAt | string | Fecha de creación de la cuenta |
Listado de tus aplicaciones y bases de datos
api.GetApplications() y api.GetDatabases() listan todo lo que posees a través del endpoint /users/me, devolviendo descriptores compactos 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 — consulta Gestionar aplicaciones y Bases de datos.
Listado del historial de snapshots (a nivel de cuenta)
api.UserSnapshots(scope) devuelve todos los snapshots que posees para un dominio dado:
appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
panic(err)
}
dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
panic(err)
}
api.ServiceStatus() expone el estado de salud agregado de la plataforma (los mismos datos que se muestran en la página de estado pública).
status, err := api.ServiceStatus()
if err != nil {
panic(err)
}
fmt.Println(status.Status) // "ok" | "degraded" | "down"
fmt.Println(status.Message) // resumen legible para humanos
A diferencia de la mayoría de los endpoints v2, esta ruta no envuelve su payload en el sobre estándar { status, code, response } — responde directamente con { status, message }.
Opciones de solicitud
Cada método acepta ...rest.RequestOpts al final para personalizar la solicitud individual:
| Opción | Descripción |
|---|
rest.WithContext(ctx) | Adjunta un context.Context para cancelación o deadlines |
rest.WithQueryParam(key, value) | Añade un parámetro de query |
rest.WithHeader(key, value) | Establece un header de la solicitud |
rest.WithToken(token) | Sobrescribe el token de autenticación solo para esta solicitud |
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
panic(err)
}
Manejo de errores
Cualquier respuesta no-2xx se devuelve como un *rest.APIError que expone StatusCode, Code y Message. Desenvuélvelo con el idiomático 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 — devuelve el código de error de la API (o "" cuando el error no es un *rest.APIError)rest.IsRateLimit(err) bool — indica si el error es alguno de los códigos de rate limit (KEEP_CALM, RATE_LIMIT, RATE_LIMIT_EXCEEDED, RATELIMIT, DELAY_NOW)
if err != nil {
if rest.IsRateLimit(err) {
time.Sleep(5 * time.Second)
// reintentar...
}
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 — consulta la tabla completa de códigos en la referencia del SDK de JS.
