> ## 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

> Le package rest est le point d'entrée du SDK Go. Instanciez un client avec une clé d'API et accédez à chaque ressource — applications, bases de données, workspaces, utilisateur et service de plateforme — via une interface unique.

## 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](https://squarecloud.app/fr/dashboard) sous **My Account → Regenerate API/CLI KEY**

## Installation

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

Le module fournit deux packages :

| 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

```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...)` 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 `ConfigOpt`s 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é                          |

```go theme={null}
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](/fr/sdks/go/managing_application) |
| `Databases`    | Création, gestion, identifiants et snapshots                                                | [Bases de données](/fr/sdks/go/databases)                    |
| `Workspaces`   | Création, membres, applications partagées                                                   | [Workspaces](/fr/sdks/go/workspaces)                         |

## Récupérer l'utilisateur authentifié

`api.SelfUser()` renvoie un `squarecloud.User` contenant les détails du compte et le plan actuel.

```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)         // 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` :

```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)
}
```

Pour récupérer l'enregistrement complet d'une seule ressource, utilisez `GetApplication` / `GetDatabase` — consultez [Gestion des applications](/fr/sdks/go/managing_application) et [Bases de données](/fr/sdks/go/databases).

## Lister l'historique des snapshots (à l'échelle du compte)

`api.UserSnapshots(scope)` renvoie tous les snapshots que vous possédez pour un domaine donné :

```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)
}
```

Consultez [Snapshots](/fr/sdks/go/snapshots) pour plus de détails sur les charges utiles des snapshots.

## État de la plateforme

`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).

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

<Note>
  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 }`.
</Note>

## Options de requête

Chaque méthode accepte des `...rest.RequestOpt`s 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   |

```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)
}
```

## 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` :

```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
}
```

Deux helpers simplifient les vérifications courantes :

* `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`)

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

Les codes d'erreur sont les mêmes que ceux utilisés par `@squarecloud/api-types` — consultez la [table complète des codes dans la référence du SDK JS](/fr/sdks/js/client#codes-derreur-apierrorcode).