Install
Terminal · npx$
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-native-skillsWorks with Paperclip
How Ios Networking fits into a Paperclip company.
Ios Networking drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.
S
SaaS FactoryPaired
Pre-configured AI company — 18 agents, 18 skills, one-time purchase.
$27$59
Explore packSource file
SKILL.md441 linesExpandCollapse
---name: ios-networkingdescription: "Build, review, or improve networking code in iOS/macOS apps using URLSession with async/await, structured concurrency, and modern Swift patterns. Use when working with REST APIs, downloading files, uploading data, WebSocket connections, pagination, retry logic, request middleware, caching, background transfers, or network reachability monitoring. Also use when handling HTTP requests, API clients, network error handling, or data fetching in Swift apps."--- # iOS Networking Modern networking patterns for iOS 26+ using URLSession with async/await andstructured concurrency. All examples target Swift 6.3. No third-partydependencies required -- URLSession covers the vast majority of networkingneeds. ## Contents - [Core URLSession async/await](#core-urlsession-asyncawait)- [API Client Architecture](#api-client-architecture)- [Error Handling](#error-handling)- [Pagination](#pagination)- [Network Reachability](#network-reachability)- [Configuring URLSession](#configuring-urlsession)- [Common Mistakes](#common-mistakes)- [Review Checklist](#review-checklist)- [References](#references) ## Core URLSession async/await URLSession gained native async/await overloads in iOS 15. These are theonly networking APIs to use in new code. Never use completion-handlervariants in new projects. ### Data Requests ```swift// Basic GETlet (data, response) = try await URLSession.shared.data(from: url) // With a configured URLRequestvar request = URLRequest(url: url)request.httpMethod = "POST"request.setValue("application/json", forHTTPHeaderField: "Content-Type")request.httpBody = try JSONEncoder().encode(payload)request.timeoutInterval = 30request.cachePolicy = .reloadIgnoringLocalCacheData let (data, response) = try await URLSession.shared.data(for: request)``` ### Response Validation Always validate the HTTP status code before decoding. URLSession does notthrow for 4xx/5xx responses -- it only throws for transport-level failures. ```swiftguard let httpResponse = response as? HTTPURLResponse else { throw NetworkError.invalidResponse} guard (200..<300).contains(httpResponse.statusCode) else { throw NetworkError.httpError( statusCode: httpResponse.statusCode, data: data )}``` ### JSON Decoding with Codable ```swiftfunc fetch<T: Decodable>(_ type: T.Type, from url: URL) async throws -> T { let (data, response) = try await URLSession.shared.data(from: url) guard let httpResponse = response as? HTTPURLResponse, (200..<300).contains(httpResponse.statusCode) else { throw NetworkError.invalidResponse } let decoder = JSONDecoder() decoder.dateDecodingStrategy = .iso8601 decoder.keyDecodingStrategy = .convertFromSnakeCase return try decoder.decode(T.self, from: data)}``` ### Downloads and Uploads Use `download(for:)` for large files -- it streams to disk instead ofloading the entire payload into memory. ```swift// Download to a temporary filelet (localURL, response) = try await URLSession.shared.download(for: request) // Move from temp location before the method returnslet destination = documentsDirectory.appendingPathComponent("file.zip")try FileManager.default.moveItem(at: localURL, to: destination)``` ```swift// Upload datalet (data, response) = try await URLSession.shared.upload(for: request, from: bodyData) // Upload from filelet (data, response) = try await URLSession.shared.upload(for: request, fromFile: fileURL)``` ### Streaming with AsyncBytes Use `bytes(for:)` for streaming responses, progress tracking, orline-delimited data (e.g., server-sent events). ```swiftlet (bytes, response) = try await URLSession.shared.bytes(for: request) for try await line in bytes.lines { // Process each line as it arrives (e.g., SSE stream) handleEvent(line)}``` ## API Client Architecture ### Protocol-Based Client Define a protocol for testability. This lets you swap implementations intests without mocking URLSession directly. ```swiftprotocol APIClientProtocol: Sendable { func fetch<T: Decodable & Sendable>( _ type: T.Type, endpoint: Endpoint ) async throws -> T func send<T: Decodable & Sendable>( _ type: T.Type, endpoint: Endpoint, body: some Encodable & Sendable ) async throws -> T}``` ```swiftstruct Endpoint: Sendable { let path: String var method: String = "GET" var queryItems: [URLQueryItem] = [] var headers: [String: String] = [:] func url(relativeTo baseURL: URL) -> URL { guard let components = URLComponents( url: baseURL.appendingPathComponent(path), resolvingAgainstBaseURL: true ) else { preconditionFailure("Invalid URL components for path: \(path)") } var mutableComponents = components if !queryItems.isEmpty { mutableComponents.queryItems = queryItems } guard let url = mutableComponents.url else { preconditionFailure("Failed to construct URL from components") } return url }}``` The client accepts a `baseURL`, optional custom `URLSession`, `JSONDecoder`,and an array of `RequestMiddleware` interceptors. Each method builds a`URLRequest` from the endpoint, applies middleware, executes the request,validates the status code, and decodes the result. See[references/urlsession-patterns.md](references/urlsession-patterns.md) for the complete `APIClient` implementationwith convenience methods, request builder, and test setup. ### Lightweight Closure-Based Client For apps using the MV pattern, use closure-based clients for testabilityand SwiftUI preview support. See [references/lightweight-clients.md](references/lightweight-clients.md) forthe full pattern (struct of async closures, injected via init). ### Request Middleware / Interceptors Middleware transforms requests before they are sent. Use this forauthentication, logging, analytics headers, and similar cross-cuttingconcerns. ```swiftprotocol RequestMiddleware: Sendable { func prepare(_ request: URLRequest) async throws -> URLRequest}``` ```swiftstruct AuthMiddleware: RequestMiddleware { let tokenProvider: @Sendable () async throws -> String func prepare(_ request: URLRequest) async throws -> URLRequest { var request = request let token = try await tokenProvider() request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization") return request }}``` ### Token Refresh Flow Handle 401 responses by refreshing the token and retrying once. ```swiftfunc fetchWithTokenRefresh<T: Decodable & Sendable>( _ type: T.Type, endpoint: Endpoint, tokenStore: TokenStore) async throws -> T { do { return try await fetch(type, endpoint: endpoint) } catch NetworkError.httpError(statusCode: 401, _) { try await tokenStore.refreshToken() return try await fetch(type, endpoint: endpoint) }}``` ## Error Handling ### Structured Error Types ```swiftenum NetworkError: Error, Sendable { case invalidResponse case httpError(statusCode: Int, data: Data) case decodingFailed(Error) case noConnection case timedOut case cancelled /// Map a URLError to a typed NetworkError static func from(_ urlError: URLError) -> NetworkError { switch urlError.code { case .notConnectedToInternet, .networkConnectionLost: return .noConnection case .timedOut: return .timedOut case .cancelled: return .cancelled default: return .httpError(statusCode: -1, data: Data()) } }}``` ### Key URLError Cases | URLError Code | Meaning | Action ||---|---|---|| `.notConnectedToInternet` | Device offline | Show offline UI, queue for retry || `.networkConnectionLost` | Connection dropped mid-request | Retry with backoff || `.timedOut` | Server did not respond in time | Retry once, then show error || `.cancelled` | Task was cancelled | No action needed; do not show error || `.cannotFindHost` | DNS failure | Check URL, show error || `.secureConnectionFailed` | TLS handshake failed | Check cert pinning, ATS config || `.userAuthenticationRequired` | 401 from proxy | Trigger auth flow | ### Decoding Server Error Bodies ```swiftstruct APIErrorResponse: Decodable, Sendable { let code: String let message: String} func decodeAPIError(from data: Data) -> APIErrorResponse? { try? JSONDecoder().decode(APIErrorResponse.self, from: data)} // Usage in catch blockcatch NetworkError.httpError(let statusCode, let data) { if let apiError = decodeAPIError(from: data) { showError("Server error: \(apiError.message)") } else { showError("HTTP \(statusCode)") }}``` ### Retry with Exponential Backoff Use structured concurrency for retries. Respect task cancellation betweenattempts. Skip retries for cancellation and 4xx client errors (except 429). ```swiftfunc withRetry<T: Sendable>( maxAttempts: Int = 3, initialDelay: Duration = .seconds(1), operation: @Sendable () async throws -> T) async throws -> T { var lastError: Error? for attempt in 0..<maxAttempts { do { return try await operation() } catch { lastError = error if error is CancellationError { throw error } if case NetworkError.httpError(let code, _) = error, (400..<500).contains(code), code != 429 { throw error } if attempt < maxAttempts - 1 { try await Task.sleep(for: initialDelay * Int(pow(2.0, Double(attempt)))) } } } throw lastError!}``` ## Pagination Build cursor-based or offset-based pagination with `AsyncSequence`.Always check `Task.isCancelled` between pages. See[references/urlsession-patterns.md](references/urlsession-patterns.md) for complete `CursorPaginator` andoffset-based implementations. ## Network Reachability Use `NWPathMonitor` from the Network framework — not third-partyReachability libraries. Wrap in `AsyncStream` for structured concurrency. ```swiftimport Network func networkStatusStream() -> AsyncStream<NWPath.Status> { AsyncStream { continuation in let monitor = NWPathMonitor() monitor.pathUpdateHandler = { continuation.yield($0.status) } continuation.onTermination = { _ in monitor.cancel() } monitor.start(queue: DispatchQueue(label: "NetworkMonitor")) }}``` Check `path.isExpensive` (cellular) and `path.isConstrained` (Low DataMode) to adapt behavior (reduce image quality, skip prefetching). ## Configuring URLSession Create a configured session for production code. `URLSession.shared` isacceptable only for simple, one-off requests. ```swiftlet configuration = URLSessionConfiguration.defaultconfiguration.timeoutIntervalForRequest = 30configuration.timeoutIntervalForResource = 300configuration.waitsForConnectivity = trueconfiguration.requestCachePolicy = .returnCacheDataElseLoadconfiguration.httpAdditionalHeaders = [ "Accept": "application/json", "Accept-Language": Locale.preferredLanguages.first ?? "en"] let session = URLSession(configuration: configuration)``` `waitsForConnectivity = true` is valuable -- it makes the session wait fora network path instead of failing immediately when offline. Combine with`urlSession(_:taskIsWaitingForConnectivity:)` delegate callback for UIfeedback. ## Common Mistakes **DON'T:** Use `URLSession.shared` with custom configuration needs.**DO:** Create a configured `URLSession` with appropriate timeouts, caching,and delegate for production code. **DON'T:** Force-unwrap `URL(string:)` with dynamic input.**DO:** Use `URL(string:)` with proper error handling. Force-unwrap isacceptable only for compile-time-constant strings. **DON'T:** Decode JSON on the main thread for large payloads.**DO:** Keep decoding on the calling context of the URLSession call, whichis off-main by default. Only hop to `@MainActor` to update UI state. **DON'T:** Ignore cancellation in long-running network tasks.**DO:** Check `Task.isCancelled` or call `try Task.checkCancellation()` inloops (pagination, streaming, retry). Use `.task` in SwiftUI for automaticcancellation. **DON'T:** Use Alamofire or Moya when URLSession async/await handles theneed.**DO:** Use URLSession directly. With async/await, the ergonomic gap thatjustified third-party libraries no longer exists. Reserve third-partylibraries for genuinely missing features (e.g., image caching). **DON'T:** Mock URLSession directly in tests.**DO:** Use `URLProtocol` subclass for transport-level mocking, or useprotocol-based clients that accept a test double. **DON'T:** Use `data(for:)` for large file downloads.**DO:** Use `download(for:)` which streams to disk and avoids memory spikes. **DON'T:** Fire network requests from `body` or view initializers.**DO:** Use `.task` or `.task(id:)` to trigger network calls. **DON'T:** Hardcode authentication tokens in requests.**DO:** Inject tokens via middleware so they are centralized and refreshable. **DON'T:** Ignore HTTP status codes and decode blindly.**DO:** Validate status codes before decoding. A 200 with invalid JSON anda 500 with an error body require different handling. ## Review Checklist - [ ] All network calls use async/await (not completion handlers)- [ ] Error handling covers URLError cases (.notConnectedToInternet, .timedOut, .cancelled)- [ ] Requests are cancellable (respect Task cancellation via `.task` modifier or stored Task references)- [ ] Authentication tokens injected via middleware, not hardcoded- [ ] Response HTTP status codes validated before decoding- [ ] Large downloads use `download(for:)` not `data(for:)`- [ ] Network calls happen off `@MainActor` (only UI updates on main)- [ ] URLSession configured with appropriate timeouts and caching- [ ] Retry logic excludes cancellation and 4xx client errors- [ ] Pagination checks `Task.isCancelled` between pages- [ ] Sensitive tokens stored in Keychain (not UserDefaults or plain files)- [ ] No force-unwrapped URLs from dynamic input- [ ] Server error responses decoded and surfaced to users- [ ] Ensure network response model types conform to Sendable; use @MainActor for UI-updating completion paths ## References - See [references/urlsession-patterns.md](references/urlsession-patterns.md) for complete API client implementation, multipart uploads, download progress, URLProtocol mocking, retry/backoff, certificate pinning, request logging, and pagination implementations.- See [references/background-websocket.md](references/background-websocket.md) for background URLSession configuration, background downloads/uploads, WebSocket patterns with structured concurrency, and reconnection strategies.- See [references/lightweight-clients.md](references/lightweight-clients.md) for the lightweight closure-based client pattern (struct of async closures, injected via init for testability and preview support).- See [references/network-framework.md](references/network-framework.md) for Network.framework (NWConnection, NWListener, NWBrowser, NWPathMonitor) and low-level TCP/UDP/WebSocket patterns.