Swift

The Swift SDK is distributed by git tag. Swift Package Manager resolves straight from a repository, so there is no registry account to connect. The package supports iOS 15, macOS 12, tvOS 15 and watchOS 8, uses URLSession (with FoundationNetworking on Linux), and has no package dependencies.

Install

Add it in Xcode under File → Add Packages, or in Package.swift:

dependencies: [
    .package(url: "https://github.com/your-org/api-client-swift", from: "1.0.0")
]

Options

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

Synchronous companionschoicedefault: omit

include adds a …Sync method beside each asynchronous one.

syncMethods

Client stylechoicedefault: class

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

clientStyleByLang.swift

Namespacechoicedefault: tags

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

namespaceByLang.swift

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: positional

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

outputByLang.swift.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.swift.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.swift.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 Swift repository

Set Repository for Swift. It's the URL your users paste into Xcode, so it's user-facing.
Release

Octri pushes the generated code and a semver tag. SPM resolves versions from tags.

The repository URL is the dependency

There's no registry indirection: your users' Package.swift names your repo directly. Moving or renaming it breaks every consumer's resolution, and unlike Go it also breaks Xcode projects that pinned it. Pick the repo name once.

SPM reads semver tags

A release SPM can resolve is a semver tag. A pushed commit without a tag is invisible to from: "1.0.0".

What callers write

import AcmeApi

let acme = Acme(config: ClientConfig(
    baseUrl: "https://api.acme.com/v1",
    auth: ClientAuthConfig(bearer: token)
))

// listPaginated returns an AsyncThrowingStream. Pages load as you iterate.
for try await user in acme.users.listPaginated(limit: 100) {
    print(user.id)
}

Every operation is async throws with labeled arguments, and models are Codable structs. A non-2xx response throws SdkHttpError, whose kind (.notFound, .rateLimit and so on) covers the common statuses, beside statusCode and requestId.

Runtime


Requires	Swift tools 5.9 or newer
HTTP	`URLSession`
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:

for try await event in try await client.events.stream() {
    print(event.id)
}

Returns an AsyncThrowingStream. See streaming.

Handling errors

do {
    let user = try await client.users.get(id: "usr_1")
    print(user)
} catch let error as SdkHttpError {
    print(error.statusCode, error.requestId)
    if error.statusCode == 404 { return }
    throw error
}

HTTP failures are an SdkHttpError, with the status code on it. error.data holds the decoded model as any Decodable, which you can narrow with as?. See what's in the package.

The other git-tag language.

Publishing

Git-tag distribution in detail.