> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> Das Paket rest ist der Einstiegspunkt zum Go SDK. Instanziiere einen Client mit einem API-Schlüssel und greife über eine einzige Schnittstelle auf jede Ressource zu — Anwendungen, Datenbanken, Workspaces, Benutzer und Plattformdienst.

## Voraussetzungen

* **Go 1.24** oder neuer
* **Null externe Abhängigkeiten** — das SDK baut ausschließlich auf der Go-Standardbibliothek auf
* Ein gültiger API-Schlüssel — fordere einen im [Square Cloud Dashboard](https://squarecloud.app/de/dashboard) unter **My Account → Regenerate API/CLI KEY** an

## Installation

```bash theme={null}
go get github.com/squarecloudofc/sdk-api-go/v2
```

Das Modul liefert zwei Pakete:

| Paket         | Importpfad                                            | Inhalt                                                                       |
| ------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
| `rest`        | `github.com/squarecloudofc/sdk-api-go/v2/rest`        | HTTP-Client, Ressourcen-Schnittstellen, Request-Optionen, Fehler, SSE-Stream |
| `squarecloud` | `github.com/squarecloudofc/sdk-api-go/v2/squarecloud` | Jeder Request-/Response-Typ und jedes Struct                                 |

## Instanziierung des Clients

```go theme={null}
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...)` baut den zugrunde liegenden HTTP-Client; `rest.New(client)` verpackt ihn in `rest.Rest`, die Schnittstelle, die jede Ressource bereitstellt. Rufe stets `defer client.Close()` auf, um inaktive Verbindungen freizugeben.

### Client-Konfiguration (`ConfigOpt`)

`rest.NewClient` akzeptiert nach dem Token optionale `ConfigOpt`s:

| Option                              | Standard                         | Beschreibung                                          |
| ----------------------------------- | -------------------------------- | ----------------------------------------------------- |
| `rest.WithLogger(*slog.Logger)`     | verworfen                        | Strukturierter Logger für Request-/Response-Debugging |
| `rest.WithHTTPClient(*http.Client)` | 30s Timeout                      | Eigener `*http.Client` (Proxys, Transports, Timeouts) |
| `rest.WithURL(string)`              | `https://api.squarecloud.app/v2` | Basis-URL der API                                     |
| `rest.WithUserAgent(string)`        | SDK-Standard                     | Eigener `User-Agent`-Header                           |

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

## Module

`rest.Rest` bettet eine Schnittstelle pro Ressourcen-Domäne ein, dazu die auf dieser Seite dokumentierten Benutzer- und Service-Methoden:

| Schnittstelle  | Abdeckung                                                                | Dokumentation                                             |
| -------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `Applications` | Verwalten, Upload, Dateien, Envs, Snapshots, Deploys, Netzwerk, Realtime | [Anwendungen verwalten](/de/sdks/go/managing_application) |
| `Databases`    | Erstellen, Verwalten, Zugangsdaten und Snapshots                         | [Datenbanken](/de/sdks/go/databases)                      |
| `Workspaces`   | Erstellen, Mitglieder, geteilte Anwendungen                              | [Workspaces](/de/sdks/go/workspaces)                      |

## Den authentifizierten Benutzer abrufen

`api.SelfUser()` gibt einen `squarecloud.User` mit den Kontodetails und dem aktuellen Plan zurück.

```go theme={null}
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)         // plan duration, 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)
```

| Feld        | Typ                    | Beschreibung                                                 |
| ----------- | ---------------------- | ------------------------------------------------------------ |
| `ID`        | `string`               | Benutzer-ID (24 Hex-Zeichen)                                 |
| `Name`      | `string`               | Anzeigename                                                  |
| `Email`     | `string`               | Konto-E-Mail                                                 |
| `Locale`    | `string`               | Bevorzugte Locale, z. B. `"en-US"`                           |
| `Plan`      | `squarecloud.UserPlan` | `Name`, `Memory{Limit, Available, Used}` (MB) und `Duration` |
| `CreatedAt` | `string`               | Erstellungsdatum des Kontos                                  |

## Deine Anwendungen und Datenbanken auflisten

`api.GetApplications()` und `api.GetDatabases()` listen über den Endpoint `/users/me` alles auf, was dir gehört, und geben kompakte `squarecloud.UserApplication`- / `squarecloud.UserDatabase`-Deskriptoren zurück:

```go theme={null}
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)
}
```

Um den vollständigen Datensatz einer einzelnen Ressource abzurufen, verwende `GetApplication` / `GetDatabase` — siehe [Anwendungen verwalten](/de/sdks/go/managing_application) und [Datenbanken](/de/sdks/go/databases).

## Snapshot-Verlauf auflisten (kontoweit)

`api.UserSnapshots(scope)` gibt jeden Snapshot zurück, den du in einer gegebenen Domäne besitzt:

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

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

Siehe [Snapshots](/de/sdks/go/snapshots) für Details zu Snapshot-Payloads.

## Plattformstatus

`api.ServiceStatus()` stellt den aggregierten Plattformzustand bereit (dieselben Daten, die auf der öffentlichen Statusseite angezeigt werden).

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

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // human-readable summary
```

<Note>
  Anders als die meisten v2-Endpoints kapselt diese Route ihr Payload **nicht** in den Standard-Envelope `{ status, code, response }` — sie antwortet direkt mit `{ status, message }`.
</Note>

## Request-Optionen

Jede Methode akzeptiert am Ende `...rest.RequestOpt`s, um den einzelnen Request anzupassen:

| Option                            | Beschreibung                                                     |
| --------------------------------- | ---------------------------------------------------------------- |
| `rest.WithContext(ctx)`           | Hängt einen `context.Context` für Abbruch oder Deadlines an      |
| `rest.WithQueryParam(key, value)` | Fügt einen Query-Parameter hinzu                                 |
| `rest.WithHeader(key, value)`     | Setzt einen Request-Header                                       |
| `rest.WithToken(token)`           | Überschreibt das Authentifizierungs-Token nur für diesen Request |

```go theme={null}
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

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

## Fehlerbehandlung

Jede Nicht-2xx-Antwort wird als `*rest.APIError` zurückgegeben, der `StatusCode`, `Code` und `Message` bereitstellt. Entpacke ihn mit dem idiomatischen `errors.As`:

```go theme={null}
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
}
```

Zwei Helfer vereinfachen häufige Prüfungen:

* `rest.ErrorCode(err) string` — gibt den API-Fehlercode zurück (oder `""`, wenn der Fehler kein `*rest.APIError` ist)
* `rest.IsRateLimit(err) bool` — meldet, ob der Fehler einer der Rate-Limit-Codes ist (`KEEP_CALM`, `RATE_LIMIT`, `RATE_LIMIT_EXCEEDED`, `RATELIMIT`, `DELAY_NOW`)

```go theme={null}
if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// retry...
	}

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

Die Fehlercodes sind dieselben, die `@squarecloud/api-types` verwendet — siehe die [vollständige Code-Tabelle in der JS-SDK-Referenz](/de/sdks/js/client#fehlercodes-apierrorcode).