Go SDK — Začínáme

sdk-go je Go klient pro Sencai Platform API (/api/v1/*), generovaný z veřejného OpenAPI specu (openapi-generator-cli, šablona go — F4.DEVPORTAL.02). Žije v monorepu na sdk-go/, modul github.com/sencai/sdk-go.

Instalace

github.com/sencai/sdk-go je placeholder import cesta, zatím nepublikovaná — finální cesta modulu je rozhodnutí navázané na budoucí veřejný release (vlastní repozitář/organizace) a veřejná indexace na pkg.go.dev je samostatné obchodní/release rozhodnutí, mimo scope samotné práce na generování SDK. Do té doby:

go get github.com/sencai/sdk-go

a do go.mod konzumujícího projektu přidat replace direktivu mířící na lokální checkout nebo git ref tohoto adresáře:

replace github.com/sencai/sdk-go => /path/to/code/sdk-go

Inicializace klienta

package main

import (
  "context"
  "os"

  sencaisdk "github.com/sencai/sdk-go"
)

func main() {
  cfg := sencaisdk.NewConfiguration()
  cfg.Servers = sencaisdk.ServerConfigurations{
    // Lokální vývoj: http://api.sencai.localhost/api/v1 nebo http://localhost:1337/api/v1
    // Produkce: https://api.sencai.space/api/v1
    {URL: os.Getenv("SENCAI_API_BASE_URL")},
  }
  // Bearer JWT (dnes Keycloak access token) — nebo budoucí API-key hlavička.
  // Klient jen umožňuje injection, sám token nezískává ani neobnovuje.
  cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("SENCAI_ACCESS_TOKEN"))

  client := sencaisdk.NewAPIClient(cfg)
  ctx := context.Background()
  _ = ctx
  _ = client
}

Configuration.Servers i hlavička Authorization se vždy nastavují za běhu — balíček nikdy neobsahuje hardcoded produkční URL.

Kompletní příklad: seznam organizací, pozvání člena

Ověřeno proti lokálnímu stacku run-local-dev.sh (profily backend, backend-db, auth).

package main

import (
  "context"
  "fmt"
  "os"

  sencaisdk "github.com/sencai/sdk-go"
)

func main() {
  cfg := sencaisdk.NewConfiguration()
  cfg.Servers = sencaisdk.ServerConfigurations{{URL: os.Getenv("SENCAI_API_BASE_URL")}}
  cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("SENCAI_ACCESS_TOKEN"))
  client := sencaisdk.NewAPIClient(cfg)
  ctx := context.Background()

  // Seznam organizací, jejichž je volající členem.
  result, _, err := client.OrganisationAPI.FindOrganisation(ctx).PaginationPageSize(10).Execute()
  if err != nil {
    panic(err)
  }
  for _, org := range result.Data {
    fmt.Println(org.Name)
  }
  // -> QA Admin Workspace
  //    e2e-org-d18a54e2
  //    e2e-org-d9e67836

  targetOrg := result.Data[0]

  // Pozvání existujícího Strapi uživatele do dané organizace. `POST
  // /organisations/{id}/invite` vyžaduje, aby zvaný email už měl
  // registrovaný účet (viz sekce Zpracování chyb níže, co se stane jinak)
  // a aby volající měl v organizaci roli admin+.
  body := sencaisdk.NewOrganisationInviteMemberRequest("new-member@example.com", "viewer")
  invite, _, err := client.OrganisationAPI.
    OrganisationInviteMember(ctx, *targetOrg.DocumentId).
    OrganisationInviteMemberRequest(*body).
    Execute()
  if err != nil {
    panic(err)
  }
  fmt.Printf("%+v\n", invite.Data)
}

Zpracování chyb

Non-2xx odpověď vrátí nenulovou error (typovaná metoda vrátí svou nulovou hodnotu), kterou lze odbalit na *sencaisdk.GenericOpenAPIError — ten poskytuje syrové tělo odpovědi přes .Body(). Tělo chyby má standardní Strapi obálku: { "error": { "status", "name", "message", "details" } }.

import (
  "encoding/json"
  "errors"
)

type errorEnvelope struct {
  Error struct {
    Status  int            `json:"status"`
    Name    string         `json:"name"`
    Message string         `json:"message"`
    Details map[string]any `json:"details"`
  } `json:"error"`
}

_, _, err := client.OrganisationAPI.
  OrganisationInviteMember(ctx, *targetOrg.DocumentId).
  OrganisationInviteMemberRequest(*body).
  Execute()
if err != nil {
  var apiErr *sencaisdk.GenericOpenAPIError
  if errors.As(err, &apiErr) {
    var body errorEnvelope
    _ = json.Unmarshal(apiErr.Body(), &body)
    fmt.Println(body.Error.Status, body.Error.Name, body.Error.Message)
    // Reálný, běžně narazitelný příklad — limit počtu členů z tarifu organizace:
    // 402 PaymentRequired "Member limit reached (3/3). Upgrade your plan."
  }
}

Další stavové kódy, které lze u tohoto konkrétního endpointu očekávat: 400 (chybějící/neplatný email/role, nebo žádný Strapi uživatel s daným emailem — tento endpoint nezve ještě neregistrované emaily), 401 (chybějící/expirovaný token), 403 (volající nemá v organizaci roli admin+), 409 (daný uživatel je již členem).

Verzování SDK a breaking changes

Verze balíčku je sledovaná v .openapi-generator/VERSION a při každé regeneraci odvozená z info.version OpenAPI specu — nikdy se nebumpuje ručně. Verzování samotného Go modulu jde přes git tagy na samostatném repozitáři, jakmile vznikne (mimo scope tohoto úkolu). Breaking change API se vydá jako nová major verze specu, což přeregeneruje toto SDK odpovídajícím způsobem. Co se počítá jako breaking, migrační cestu /api/v1/ → /api/v2/ a konvenci deprecation hlavičky SUNSET_DATE viz Verzování API — tato stránka danou politiku neopakuje, jen popisuje, jak se projevuje v generovaném klientovi.

Kompletní generovanou referenci každé operace, kterou tento klient pokrývá, najdeš v API Reference.