{"id":"l-sw-4-2","courseId":"swift-essentials","lang":"en","kind":"lesson","summary":"Fetch JSON with URLSession’s async API, check the HTTP status, decode it into Codable structs, and show loading, loaded and failed states in SwiftUI.","html":"

Pocket Budget records expenses in dollars, but you spend money on holiday in euros and Egyptian pounds. To convert, the app needs today’s exchange rates from a server. This lesson replaces the pretend Task.sleep from the last lesson with a real request: build a URL, fetch the data, check the response, decode the JSON into Swift types and show it. Those steps are the same for nearly every API you will ever call.

\n

The examples use a stand-in endpoint, https://api.example.com/v1/latest?base=USD. Swap in a real exchange-rate provider (most have a free tier) and adjust the struct to match its JSON. The response looks like this:

\n
JSON
{\n  \"base\": \"USD\",\n  \"updated_at\": \"2026-10-02T06:00:00Z\",\n  \"rates\": { \"EUR\": 0.92, \"GBP\": 0.79, \"EGP\": 48.31 }\n}
\n

Mirror the JSON with Codable

\n
RatesResponse.swift
import Foundation\n\nstruct RatesResponse: Decodable {\n    let base: String\n    let updatedAt: Date\n    let rates: [String: Decimal]\n}
\n

Decodable asks the compiler to generate the code that reads this type from an external format. Property names must match the JSON keys and the types must fit: a JSON object becomes a dictionary, a number can decode into Decimal, and a missing key or wrong type throws a DecodingError that names the problem. Use Codable (Decodable plus Encodable) when you also send the type back. The struct is made of Sendable parts, so it’s Sendable too and can travel safely from the network code to the main actor.

\n

The JSON says updated_at; Swift style says updatedAt. Rather than renaming properties, configure the decoder, as the client below does.

\n

Fetch, check, decode

\n
RateClient.swift
enum RateError: Error {\n    case badStatus(Int)\n}\n\nstruct RateClient {\n    let endpoint = URL(string: \"https://api.example.com/v1/latest\")!\n\n    func latest(base: String) async throws -> RatesResponse {\n        let url = endpoint.appending(queryItems: [URLQueryItem(name: \"base\", value: base)])\n\n        let (data, response) = try await URLSession.shared.data(from: url)\n\n        let status = (response as? HTTPURLResponse)?.statusCode ?? 0\n        guard status == 200 else {\n            throw RateError.badStatus(status)\n        }\n\n        let decoder = JSONDecoder()\n        decoder.keyDecodingStrategy = .convertFromSnakeCase\n        decoder.dateDecodingStrategy = .iso8601\n        return try decoder.decode(RatesResponse.self, from: data)\n    }\n}
\n

Walk through it in order. appending(queryItems:) builds ...latest?base=USD and percent-encodes values for you, which is safer than gluing strings together. The force unwrap on URL(string:) is the acceptable kind from the optionals lesson: a literal you wrote, where nil would mean a typo.

\n

URLSession.shared.data(from:) is the async API: it suspends until the whole response has arrived and returns the body bytes plus a URLResponse. It throws for transport failures, such as no connection, a timeout or cancellation, but it does not throw for HTTP errors. That’s what the guard is for.

\n

.convertFromSnakeCase maps updated_at to updatedAt for every key, and .iso8601 reads the timestamp format most APIs use. Then decode either returns a fully formed RatesResponse or throws.

\n
\n Five steps left to right: build the URL, fetch with data(from:), check the status code, decode JSON into RatesResponse, then set state on the main actor so the view updates.\n \n Build URL\n query items\n \n \n Fetch\n data(from:)\n \n \n Check\n status 200\n \n \n Decode\n JSONDecoder\n \n \n Show\n main actor\n Any step can throw; one catch in the model turns it into the failed state\n
From URL to pixels
\n\n

Not every failure deserves the same message, either. A thrown URLError carries a code, so you can tell “offline” (.notConnectedToInternet) apart from “timed out” (.timedOut) and say “You’re offline. Rates will refresh when you reconnect” instead of a generic apology. Users forgive an app that explains itself.

\n

Loading states the view can trust

\n

The enum idea from the enums lesson now pays off. A model on the main actor owns the state, and the view switches over it:

\n
RatesModel.swift
@MainActor\n@Observable\nfinal class RatesModel {\n    enum LoadState {\n        case idle\n        case loading\n        case loaded(RatesResponse)\n        case failed(String)\n    }\n\n    var state: LoadState = .idle\n    private let client = RateClient()\n\n    func load() async {\n        state = .loading\n        do {\n            let response = try await client.latest(base: \"USD\")\n            state = .loaded(response)\n        } catch {\n            state = .failed(error.localizedDescription)\n        }\n    }\n}
\n
RatesView.swift
struct RatesView: View {\n    @State private var model = RatesModel()\n\n    var body: some View {\n        List {\n            switch model.state {\n            case .idle, .loading:\n                ProgressView()\n            case .loaded(let response):\n                ForEach(response.rates.keys.sorted(), id: \\.self) { code in\n                    LabeledContent(code, value: response.rates[code] ?? 0,\n                                   format: .number.precision(.fractionLength(2...4)))\n                }\n            case .failed(let message):\n                ContentUnavailableView(\"Couldn't load rates\",\n                                       systemImage: \"wifi.exclamationmark\",\n                                       description: Text(message))\n            }\n        }\n        .navigationTitle(\"Exchange Rates\")\n        .task { await model.load() }\n        .refreshable { await model.load() }\n    }\n}
\n

.task loads once when the screen appears, and .refreshable adds pull-to-refresh with the same function. Because RatesModel is @MainActor, assigning state is always safe for the UI, and Swift 6 checks that for you. Every error path ends in .failed, so the user never stares at a spinner that will never stop. Dictionary keys have no order, so the view sorts them for a stable list.

\n\n

iOS also requires HTTPS by default through App Transport Security, so a plain http:// URL fails unless you add an exception. Use HTTPS and you’ll never need one.

\n

Pocket Budget can now talk to the outside world. It still forgets its own expenses when you quit, so next you’ll save them on the device with SwiftData.

\n","toc":[{"id":"sec-1","text":"Mirror the JSON with Codable","level":2},{"id":"sec-2","text":"Fetch, check, decode","level":2},{"id":"sec-3","text":"Loading states the view can trust","level":2}],"takeaways":["try await URLSession.shared.data(from: url) returns the body and the response; it throws for network failures but not for HTTP errors like 404 or 500.","Always check the HTTPURLResponse status code before decoding, and turn a bad status into your own error.","Mirror the JSON with Decodable structs; keyDecodingStrategy and dateDecodingStrategy handle snake_case keys and ISO 8601 dates.","Model the screen’s lifecycle as a LoadState enum so loading, data and errors can never be shown at the same time."],"further":[{"title":"Fetching website data into memory","url":"https://developer.apple.com/documentation/foundation/fetching-website-data-into-memory"},{"title":"Encoding and Decoding Custom Types","url":"https://developer.apple.com/documentation/foundation/encoding-and-decoding-custom-types"},{"title":"URLSession","url":"https://developer.apple.com/documentation/foundation/urlsession"}],"quiz":[{"q":"

The server answers a request with HTTP 500 and an HTML error page. What does try await URLSession.shared.data(from: url) do?

","options":[{"text":"It throws a URLError with the status code.","why":"URLSession only throws when the request couldn’t complete. A 500 is a complete response."},{"text":"It returns the HTML as data and a response whose statusCode is 500.","why":"Correct. That’s why you check the status yourself before decoding."},{"text":"It retries automatically until it gets a 200.","why":"URLSession doesn’t retry on HTTP errors; retry policy is up to you."}],"answer":1},{"q":"

The JSON has a key updated_at, and your struct has let updatedAt: Date. Decoding fails with keyNotFound. What’s the smallest fix?

","options":[{"text":"Rename the property to updated_at.","why":"It works, but it drags the server’s naming style into your Swift code."},{"text":"Make the property optional: let updatedAt: Date?.","why":"The error disappears, but the date is now always nil because the key still doesn’t match."},{"text":"Set decoder.keyDecodingStrategy = .convertFromSnakeCase.","why":"Correct. The decoder maps updated_at to updatedAt for every key, so your Swift names stay idiomatic."}],"answer":2},{"q":"

Why does the rates screen use one LoadState enum instead of isLoading, rates and errorMessage properties?

","options":[{"text":"Separate properties allow impossible combinations, such as loading and failed at once; the enum allows exactly one state.","why":"Correct. The view switches over the enum and handles each state exactly once."},{"text":"SwiftUI can only observe one property per class.","why":"Observation tracks every property a body reads; that’s not the reason."},{"text":"Enums make network requests faster.","why":"The enum changes how state is modelled, not how fast the request runs."}],"answer":0}],"exercise":{"kind":"order","items":["start-task","set-loading","build-url","fetch","check-status","decode","set-loaded"],"title":"From screen appearance to rates on screen","prompt":"

Put the steps of Pocket Budget’s exchange-rate screen in the order they happen at runtime, from the moment the screen appears to the moment the rates are visible.

\n","hints":["Nothing happens until SwiftUI starts the async work, and the user should see a spinner before any network call begins.","You can’t fetch before you have a URL, and you shouldn’t decode before you know the response is a success.","The last step is the one that makes SwiftUI redraw."],"explanation":"

.task starts model.load() when the view appears. The model sets .loading first so the spinner shows immediately. The client builds the URL with its query items, then URLSession.shared.data(from:) suspends until the response arrives. The status check comes before decoding, because URLSession doesn’t throw for a 404 or 500 and an error page would fail to decode with a misleading message. Decoding produces a RatesResponse, and assigning .loaded(response) on the main actor is what makes SwiftUI re-render the list.

\n

If any step after set-loading throws, the model’s single catch sets .failed(message) instead.

\n","checkLabels":{},"itemText":{"start-task":"SwiftUI runs .task { await model.load() } as the view appears","set-loading":"The model sets state = .loading, so the view shows a ProgressView","build-url":"Build the URL: endpoint.appending(queryItems: [URLQueryItem(name: "base", value: "USD")])","fetch":"let (data, response) = try await URLSession.shared.data(from: url)","check-status":"Check (response as? HTTPURLResponse)?.statusCode == 200, otherwise throw RateError.badStatus","decode":"try decoder.decode(RatesResponse.self, from: data) with snake_case and ISO 8601 strategies","set-loaded":"Assign state = .loaded(response) on the main actor, and SwiftUI redraws the list"}},"words":696,"readMinutes":3}