Swift Academy · Lesson

Designing APIs for Value Semantics

Choosing struct vs class when designing public interfaces and frameworks.

Lesson 4 of 412 steps

Designing APIs for Value Semantics is a free Swift Academy lesson on CoddyKit. This is lesson 4 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, and your progress syncs across the web and the CoddyKit app. The Swift Academy course includes 4 lessons in total.

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?

Answer it in the interactive lesson

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.

Free to start

Learn Swift with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 122
Lessons: 409

Start learning free View the full course

Frequently Asked Questions

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

Yes — any 3 lessons of the Swift Academy learning path, including “Designing APIs for Value Semantics”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Swift Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

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