Go

The Go SDK is distributed by git tag. Go modules resolve straight from a repository, so there is no registry account to connect. The generated module declares Go 1.21 and depends on nothing outside the standard library.

Install

go get github.com/your-org/api-client-go

Options

Set these for Go in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.

Client stylechoicedefault: class

class gives callers a client to create. functions gives free functions to import. See client style.

clientStyleByLang.go

Namespacechoicedefault: tags

Groups operations by tags, by URL path, or not at all with none.

namespaceByLang.go

Method namingchoicedefault: short

short drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.

methodNaming

Argument stylechoicedefault: object

object takes one parameters object, and positional takes arguments in order. See argument style.

outputByLang.go.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.go.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.go.usageExample

File headerchoicedefault: include

include or omit. Omitting it needs the Enterprise plan. Set for every language at once.

fileHeader

Distribution

Connect the GitHub App

Octri needs push access to tag releases.
Set the Go repository

Set Repository for Go specifically. It usually differs from the repository your other languages use, for example acme-go beside acme-node.
Release

Octri pushes the generated code and a semver tag. go get resolves it from the tag.

The repository is the import path

This is the one decision in Go that you cannot walk back.

Changing the repo changes every import statement your users wrote

Go derives the module path from the repository URL and writes it into go.mod. github.com/acme/acme-go means users write:

import "github.com/acme/acme-go"

Rename or move the repo and every consumer's import breaks, with no deprecation path and no redirect. Go module paths are permanent in a way npm names are not.

Pick the Go repo name deliberately, before the first tag.

Major versions

Go encodes major versions above v1 in the module path:

github.com/acme/acme-go       v0 and v1
github.com/acme/acme-go/v2    v2 and up

v2 is a different import path

Publishing v2.0.0 means your users change their import line as well as their go.mod. That is how Go modules work in every project, and it's worth staying on v1 while you can. See Versioning.

What callers write

package main

import (
    "context"
    "errors"
    "fmt"
    "os"

    acme "github.com/acme/acme-go"
)

func main() {
    ctx := context.Background()

    client := acme.NewAcme(acme.ClientConfig{
        BaseURL: "https://api.acme.com/v1",
        Auth:    &acme.ClientAuthConfig{Bearer: os.Getenv("ACME_TOKEN")},
    })

    // The Paginated companion takes a yield callback. Return false to stop early.
    limit := int64(100)
    err := client.Users.ListPaginated(ctx, acme.ListUsersParams{Limit: &limit},
        func(user *acme.User) bool {
            fmt.Println(user.Id)
            return true
        })
    if errors.Is(err, acme.ErrRateLimit) {
        // 429 after the built-in retries.
    }
    if err != nil {
        panic(err)
    }
}

Field names are derived mechanically from your schema's property names, so id becomes Id and customer_id becomes CustomerId; the JSON tags keep the wire names exact. Common statuses are sentinels (ErrNotFound, ErrRateLimit and so on) for errors.Is, and errors.As with a *acme.SdkHttpError gives you StatusCode and RequestID.

Runtime


Requires	Go 1.21 or newer
HTTP	`net/http`
Timeout	30 seconds per attempt
Retries	Up to 3 attempts, with backoff from 500 ms to 8 seconds
Idempotency keys	`POST` and `PATCH`

Those are the defaults. See every setting and retries and timeouts to change them.

Streaming

For an operation that streams:

events, errs := client.Events.Stream(ctx)

for event := range events {
    fmt.Println(event.Id)
}
if err := <-errs; err != nil {
    log.Fatal(err)
}

A typed event channel, and a channel for the error that ended the stream. Cancel ctx to stop. See streaming.

Handling errors

_, err := client.Users.Get(ctx, params)
if errors.Is(err, acme.ErrNotFound) {
    return nil
}

var httpErr *acme.SdkHttpError
if errors.As(err, &httpErr) {
    fmt.Println(httpErr.StatusCode, httpErr.RequestID)
}

Match common statuses with errors.Is against the sentinels. httpErr.Data holds the decoded model, which you can narrow with a type switch. See what's in the package.

Publishing

Git-tag distribution in detail.

Swift

The other git-tag language.