Skip to main content
Esta página documenta github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), una reescritura del SDK. ¿Vienes de la v2? Lee la guía de migración v2 → v3.

Requisitos

El módulo no tiene dependencias aparte de la biblioteca estándar de Go y se distribuye bajo licencia MIT (la v2 era AGPL-3.0). Su nombre de paquete es squarecloud.

Instalación

Clave de API y scopes

Crea una clave en squarecloud.app/account/security. El SDK la envía tal cual en el encabezado Authorization (sin el prefijo Bearer). Una clave puede limitarse a scopes (apps:read, apps:deploy, apps:control, ai:chat, …) y a aplicaciones o bases de datos concretas:
  • Una llamada fuera de esos límites devuelve un *APIError con 403 MISSING_SCOPE o RESOURCE_NOT_ALLOWED.
  • Los métodos de listado (Account.Me, Apps.StatusAll, …) solo devuelven los recursos que la clave puede ver.
  • Una clave desconocida, revocada o caducada da 401 ACCESS_DENIED.
Mantén la clave fuera de tu código fuente y de los binarios que distribuyas. Léela del entorno o de un almacén de secretos.
Los ejemplos leen la clave de la variable de entorno SQUARECLOUD_API_KEY. Defínela en la terminal donde los ejecutes:

Crear el cliente

Guárdalo como main.go en un módulo (go mod init example.com/hello y después el go get de arriba) y ejecuta go run .. Imprime el nombre de tu cuenta y el número de aplicaciones que la clave puede ver:
squarecloud.New(apiKey, opts...) devuelve un *Client y nunca un error. Un *Client es seguro para uso concurrente: créalo una vez y compártelo entre goroutines. Como New no puede fallar, una clave vacía o compuesta solo por espacios no se rechaza ahí. En su lugar, todas las llamadas salvo Service.Status fallan localmente con INVALID_API_KEY (estado 0) antes de cualquier petición. Este código solo existe en el SDK de Go.

Opciones

Pasa las opciones a New después de la clave:
No establezcas Timeout en el *http.Client que pasas a WithHTTPClient. Ese timeout también cubre la lectura del cuerpo, así que cortaría los streams de tiempo real y las descargas de snapshots. Usa en su lugar contexts, WithTimeout y los timeouts de http.Transport.
El SDK nunca escribe logs. Para trazar las peticiones, envuelve el http.RoundTripper del cliente que pasas a WithHTTPClient.
La clave de API se guarda en un campo no exportado del cliente. fmt imprime los campos no exportados, así que no imprimas el cliente con %v ni %+v.

Ejecutar los ejemplos

Los ejemplos de las páginas del SDK de Go son fragmentos. Cada uno se ejecuta por sí solo dentro de este programa, que declara los ctx, c y appID que usan:
Pega un fragmento a la vez en main y después ejecuta goimports -w . para añadir los imports que necesite (fmt, log, time, …). Instálalo con go install golang.org/x/tools/cmd/goimports@latest, o deja que la extensión de Go de tu editor (gopls) añada los imports al guardar. Las páginas que necesitan otros ids, como una base de datos o un workspace, empiezan con su propia versión de este programa.

Módulos

Además de New y las opciones With*, el paquete exporta las constantes DefaultBaseURL y Version, el tipo APIError con una constante Code* por código de error, constantes tipadas para las entradas enumeradas (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) y un struct por cada forma de la API, que puedes usar en tu propio código:

Convenciones

Primero el context y el id, de vuelta datos tipados

Todos los métodos reciben primero un context.Context y después el id del recurso, y devuelven structs planos (sin métodos ni caché). Las etiquetas json son los nombres de campo de la propia API (created_at, version_id, lastModified, joinedAt, netIO, …), así que la referencia de la API se aplica tal cual: CreatedAt es created_at, VersionID es version_id. Los campos que la API añada más adelante se ignoran, así que nunca rompen la decodificación.
  • Las mutaciones solo devuelven un error, salvo que la API devuelva datos (Envs.*, Deploys.SetWebhook, Deploys.LinkGithubApp, Databases.ResetCredentials y los métodos Create).
  • Un resultado de tipo string es "" cuando la API no envía nada.
  • Los campos que la API puede enviar como null son punteros: comprueba si son nil antes de usarlos.
  • Los contadores y los tamaños en bytes son int64.
  • Las listas llegan completas en una sola llamada: no hay paginación.
Los grupos de recursos son campos normales de un struct, así que puedes guardar valores de método:

Aplicaciones de workspace

Todo appID acepta también la forma compuesta <appId>-<workspaceId> para actuar sobre una aplicación compartida contigo a través de un workspace. Workspaces.Get y Workspaces.List devuelven ids sin procesar; el id compuesto lo construyes tú:

Los ids se codifican

Los ids en la ruta de la URL se codifican con percent-encoding. Un id vacío, . o .. llegaría a otra ruta, así que falla localmente con INVALID_ID (estado 0) antes de enviar nada. Las rutas de workspace envían sus ids en el cuerpo: ahí, el INVALID_ID (400) viene del servidor.

Fechas

Los argumentos start y end (consulta Red) son valores time.Time, enviados como RFC 3339 en UTC (segundos enteros). En las respuestas, los strings ISO 8601 de la API se decodifican a time.Time, y los campos que la API envía como milisegundos Unix siguen siendo números (Plan.Duration y Uptime como *int64, FileEntry.LastModified como *float64): conviértelos con time.UnixMilli.

Timeouts

  • El deadline por defecto se aplica solo cuando ctx no tiene deadline. Un deadline en ctx siempre gana, sea más corto o más largo que el valor por defecto, mínimos incluidos.
  • Un único deadline cubre toda la llamada: cada intento y las esperas entre reintentos.
  • WithTimeout(0) (o cualquier d <= 0) desactiva todos los deadlines por defecto, incluidos los mínimos de 2 minutos.
Todos los métodos reciben un ctx, así que puedes limitar o cancelar cualquier llamada:
Una llamada cuyo ctx expira devuelve un *APIError con TIMEOUT, y una cuyo ctx se cancela devuelve NETWORK_ERROR, ambos con estado 0. Ambos envuelven el error del context, así que errors.Is(err, context.DeadlineExceeded) y errors.Is(err, context.Canceled) funcionan. Un bucle de tiempo real devuelve en cambio el ctx.Err() sin envolver.

Cuenta

c.Account.Me(ctx) devuelve el usuario autenticado junto con las aplicaciones y bases de datos que la clave puede ver.
c.Account.Snapshots(ctx, scope) lista todos los snapshots de la cuenta: consulta Snapshots.

Estado de la plataforma

c.Service.Status(ctx) devuelve el estado público de la plataforma. La ruta no necesita clave, y es el único método que también funciona en un cliente creado con una clave vacía.
unknown significa que la propia comprobación no pudo ejecutarse: no es una prueba de una caída.

Próximos pasos

Gestión de aplicaciones

Estado, ciclo de vida, logs y métricas.

Errores

Clase de error, reintentos y límites de tasa.

Introducción a la API

URL base, autenticación y una primera solicitud.

Inicio rápido de la CLI

Haz deploy y gestiona aplicaciones desde la terminal.