Swift Academy · Lesson

Designing APIs for Value Semantics

Choosing struct vs class when designing public interfaces and frameworks.

Designing APIs for Value Semantics is a free Swift Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Welcome

Designing APIs around value semantics leads to predictable, thread-safe, and easy-to-test code. Let's examine the principles and patterns for making that choice.

The Value Semantics Contract

A type has value semantics if: • Two independent copies are forever independent • Mutating one copy never affects the other • The type behaves like `Int` — `a = b; a += 1` leaves `b` unchanged

Public API: Prefer Value Return Types

```swift // Reference semantics — caller shares state: func getUser() -> UserClass { ... } // Value semantics — caller gets independent copy: func getUser() -> UserStruct { ... } ``` Value return types protect internal state from external mutation.

Immutable Reference Types

When a class is always immutable, it has value-like behaviour: ```swift final class Token { let value: String init(_ v: String) { value = v } // No mutable state — safe to share freely } ```

Choosing Struct Over Class Checklist

Prefer struct when: ✓ The type models data, not identity ✓ No need for inheritance ✓ Instances shouldn't be shared/aliased ✓ Equatable by comparing field values ✓ Works well with Swift Concurrency (Sendable)

Sendable and Value Semantics

Swift 6 Concurrency requires types crossing actor boundaries to be `Sendable`: ```swift struct Message: Sendable { var text: String; var timestamp: Date } // Safe to pass between actors ``` Value types with all-Sendable properties are automatically `Sendable`.

Making Class APIs Value-Safe

```swift struct Config { // Expose value snapshot instead of the class: func snapshot() -> Config { self } // copy by value semantics } // Or use a value-type DTO: struct UserDTO: Sendable { var id: UUID; var name: String } ```

Builder Pattern with Value Types

```swift struct Request { var url: URL var method: String = "GET" var headers: [String:String] = [:] func adding(header: String, value: String) -> Request { var copy = self copy.headers[header] = value return copy } } let r = Request(url: url).adding(header: "Auth", value: "Bearer x") ```

API Documentation Signal

Choosing struct over class sends a clear signal to API consumers: • "This is data — copy it freely" • "Mutating your copy won't affect mine" • "This is thread-safe to pass around" This reduces the need for defensive copying in consumer code.

When to Accept Reference Semantics

Accept class/reference semantics when: • Identity matters (`===`): two `User` objects can represent the same person • Shared mutable state is the feature: `Database`, `Cache`, `AudioEngine` • ObjC interop: UIKit, AppKit types are classes • Lifecycle callbacks: `deinit` for resource cleanup

Quick Check

Which Swift keyword marks a type as safe to pass across actor boundaries in Swift Concurrency?

Recap

Key takeaways: • Value semantics: mutations are local, no aliasing • Prefer struct for data models; class for identity/lifecycle • Immutable classes behave like value types • `Sendable` + value types = safe concurrency • Builder pattern using struct copies creates clean immutable APIs Course complete! Next: ARC and memory management patterns.

Frequently asked questions

Is the “Designing APIs for Value Semantics” lesson free?

Yes — the full text of “Designing APIs for Value Semantics” is free to read here on the web, and the Swift Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Swift Academy course, upgrade to CoddyKit PRO.

What will I learn in “Designing APIs for Value Semantics”?

Choosing struct vs class when designing public interfaces and frameworks. You practise Swift Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Swift Academy?

No prior experience is required. Swift Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Designing APIs for Value Semantics” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Swift Academy lesson?

Yes. Every Swift Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Stack vs Heap: Where Values Live
Mutation, Sharing and Unexpected Aliasing
Mixed Value/Reference Graphs
Designing APIs for Value Semantics

← Back to Swift Academy