Migración a v3

​

De un vistazo

​

Construcción y opciones

-import (
-	"github.com/squarecloudofc/sdk-api-go/v2/rest"
-	"github.com/squarecloudofc/sdk-api-go/v2/squarecloud"
-)
-client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger))
-api := rest.New(client)
-defer client.Close()
+import "github.com/squarecloudofc/sdk-api-go/v3"
+
+c := squarecloud.New(token, squarecloud.WithUserAgent(ua))

go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0

​

Método por método

​

Tipos

​

Errores

// v2
if rest.IsRateLimit(err) { ... }

// v3
var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Status == 429 {
	fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED
}

• Los fallos de red ahora son *APIError con Status 0, Code NETWORK_ERROR o TIMEOUT y el texto de la causa como Message, y envuelven la causa (errors.Is(err, context.Canceled) funciona).
• Lo mismo ocurre con las comprobaciones locales (Status 0: INVALID_ID, FILE_TOO_LARGE, INVALID_API_KEY) y con un cuerpo 2xx que no es JSON (UNKNOWN_ERROR, Invalid JSON in HTTP <status> response).
• Un cuerpo 2xx que dice "status": "error" ahora es un error (la v2 lo notificaba como éxito). Los rechazos del clúster al iniciar o detener aplicaciones y bases de datos llegan como 409 CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT o ACTION_FAILED, sin mensaje. El SDK devuelve una respuesta de tipo “ya” como error: trátala tú mismo como éxito si lo necesitas.
• Una respuesta sin código tiene Code UNKNOWN_ERROR.
• Una clave de API caducada da 401 ACCESS_DENIED, como una desconocida.
• Hay una constante Code* por cada código que documenta la API. Ahora la API envía 429 RATE_LIMITED (CodeRateLimited) donde antes enviaba RATE_LIMIT y RATE_LIMIT_EXCEEDED; CodeRateLimit y CodeRateLimitExceeded se mantienen, obsoletas.
• Todo error de AI.Chat tiene la forma de OpenAI con un código en minúsculas (access_denied, rate_limit_exceeded, server_overloaded, …), que Code contiene tal cual.
• Error() produce squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> (v2: squarecloud: <message> (<CODE>, HTTP <status>)). Compara los campos, no el texto.

​

Cambios de comportamiento

• Clave de API vacía: New("") (o una clave compuesta solo por espacios) sigue devolviendo un cliente (no puede devolver un error), pero todas las llamadas salvo Service.Status fallan localmente con INVALID_API_KEY.
• Snapshot 202: la v2 devolvía un *APIError con StatusCode 202. La v3 devuelve un SnapshotCreated con Pending: true y un error nil.
• Tiempo real: Next ahora devuelve un RealtimeEvent. Usa un switch sobre ev.Event (system, status, logs, error, message). Para los logs, imprime ev.Line (el byte \u0001/\u0002 se elimina; ev.Data sigue siendo el frame sin procesar) y usa ev.Stream para stdout/stderr. Para el estado, usa ev.Status: nunca es nil en un evento de estado y se combina superficialmente entre frames y reconexiones. Después de REALTIME_DISCONNECTED, Next devuelve io.EOF. El stream ya no muere a los 30 s, las reconexiones esperan al menos 5,5 s desde la apertura anterior y la apertura está limitada por el timeout del cliente hasta que llegan los encabezados. Consulta Tiempo real.
• Timeouts: la v2 usaba un timeout fijo de 30 s del http.Client para todo. La v3 aplica un deadline por defecto solo cuando ctx no tiene ninguno: el timeout del cliente (WithTimeout, 30 s) para la mayoría de las llamadas; al menos 2 minutos para start/stop/restart, la creación de bases de datos, la creación/restauración de snapshots y AI.Chat; ninguno para las subidas, las escrituras de archivos con más de 1 MiB de contenido y las descargas de snapshots. WithTimeout(0) los desactiva todos.
• Ventanas de red vacías: Analytics, Errors y Performance devuelven punteros nil cuando la ventana no tiene tráfico.
• Encabezados: todas las peticiones a la API envían Accept: application/json (text/event-stream para tiempo real). El User-Agent por defecto cambió de Square GO a squarecloud-sdk-go/3.0.0 (WithUserAgent lo sigue reemplazando).
• Ids: ahora todos los ids se codifican con percent-encoding como un único segmento de ruta (la v2 los pegaba tal cual en la ruta), y un id vacío, . o .. falla localmente con INVALID_ID.
• Escritura de archivos: la v2 siempre enviaba el contenido como string, lo que corrompía los archivos binarios, y no podía escribir un archivo vacío. La v3 siempre envía el contenido codificado en base64, así que cada byte se conserva, un contenido vacío escribe un archivo vacío y un contenido de más de 10 MB falla localmente con FILE_TOO_LARGE. La API responde 400 INVALID_CONTENT a un contenido que no puede decodificar.
• Lectura de archivos: la v3 siempre solicita base64 y lo decodifica, en lugar del array de bytes JSON que leía la v2 (que la API ha declarado obsoleto). Un archivo de más de 10 MB da 413 FILE_TOO_LARGE.
• Listado de archivos: listar un directorio que no existe da 404 FILE_NOT_FOUND; antes era una lista vacía.
• Snapshots: las entradas del listado incluyen VersionID y URL procedentes de la API; no se extrae nada de Key.
• Reintentos: novedad. Los errores de red en GET, los 503 UPLOAD_BUSY/ANALYTICS_BUSY y el 503 DATABASE_UNAVAILABLE en GET se reintentan dos veces por defecto; WithMaxRetries(0) restaura el comportamiento de la v2. DATABASE_UNAVAILABLE puede llegar después de que una mutación haya empezado, así que el SDK nunca lo reintenta en otros métodos; reintenta tú mismo una mutación idempotente si quieres. Consulta Reintentos.
• Versión de Go: el mínimo baja de Go 1.24 a Go 1.22.