Alamofire Patterns — Expert Decisions

Expert decision frameworks for Alamofire choices. Claude knows Alamofire syntax — this skill provides judgment calls for when Alamofire adds value and how to design interceptor chains.

Decision Trees

Alamofire vs URLSession

What networking features do you need? ├─ Basic REST calls with JSON │ └─ Modern URLSession is sufficient │ async/await + Codable works well │ ├─ Complex authentication (token refresh, retry) │ └─ Alamofire's RequestInterceptor shines │ Built-in retry coordination │ ├─ Request/Response inspection and modification │ └─ Does app need centralized logging/metrics? │ ├─ YES → Alamofire EventMonitor │ └─ NO → URLSession delegate suffices │ ├─ Certificate pinning │ └─ Alamofire ServerTrustManager simplifies this │ But URLSession can do it with delegates │ └─ Multipart uploads with progress └─ Alamofire upload API is cleaner URLSession works but more boilerplate

The trap: Adding Alamofire for simple apps. If you just need basic GET/POST with JSON, URLSession's async/await API is clean enough and avoids a dependency.

Interceptor Chain Design

What cross-cutting concerns exist? ├─ Just auth token injection │ └─ Single RequestAdapter │ ├─ Auth + retry on 401 │ └─ Authenticator pattern (Alamofire's built-in) │ Handles refresh token race conditions │ ├─ Multiple concerns (auth, logging, caching headers) │ └─ Compositor pattern │ Interceptor(adapters: [...], retriers: [...]) │ └─ Request modification varies by endpoint └─ Per-router interceptors Different Session instances or conditional logic

Retry Strategy Selection

What kind of failure? ├─ Auth failure (401) │ └─ Refresh token and retry once │ Use Authenticator, not generic retry │ ├─ Transient network error │ └─ Is request idempotent? │ ├─ YES → Retry with exponential backoff (3 attempts) │ └─ NO → Don't retry (may cause duplicates) │ ├─ Server error (5xx) │ └─ Retry for 503 (Service Unavailable) only │ Other 5xx usually won't recover │ └─ Client error (4xx except 401) └─ Never retry Request is malformed, retry won't help

NEVER Do

Interceptor Design

NEVER refresh tokens in generic retry logic:

// ❌ Race condition — multiple requests refresh simultaneously final class BadInterceptor: RequestRetrier { func retry(_ request: Request, for session: Session, dueTo error: Error, completion: @escaping (RetryResult) -> Void) { if response.statusCode == 401 { Task { try await refreshToken() // 5 requests = 5 refresh calls! completion(.retry) } } } }

// ✅ Use Alamofire's Authenticator — coordinates refresh across requests final class TokenAuthenticator: Authenticator { func refresh(_ credential: OAuthCredential, for session: Session, completion: @escaping (Result<OAuthCredential, Error>) -> Void) { // Single refresh, all waiting requests resume } }

NEVER create new Session instances per request:

// ❌ Loses connection pooling, memory inefficient func fetchUser() async throws -> User { let session = Session() // New session per call! return try await session.request(endpoint).serializingDecodable(User.self).value }

// ✅ Reuse session — connection pooling, shared interceptors final class NetworkManager { private let session: Session // Single instance

func fetchUser() async throws -> User {
    try await session.request(endpoint).serializingDecodable(User.self).value
}

}

NEVER use Interceptor for endpoint-specific logic:

// ❌ Interceptor has complex conditionals func adapt(_ urlRequest: URLRequest, ...) { if urlRequest.url?.path.contains("/admin") { // Add admin header } else if urlRequest.url?.path.contains("/public") { // Skip auth } }

// ✅ Use Router pattern — endpoint defines its own needs enum APIRouter: URLRequestConvertible { case adminEndpoint case publicEndpoint

var requiresAuth: Bool {
    switch self {
    case .adminEndpoint: return true
    case .publicEndpoint: return false
    }
}

}

Session Configuration

NEVER disable SSL validation in production:

// ❌ Security vulnerability let manager = ServerTrustManager(evaluators: [ "api.production.com": DisabledTrustEvaluator() // MITM vulnerable! ])

// ✅ Use DisabledTrustEvaluator only for development #if DEBUG let evaluator = DisabledTrustEvaluator() #else let evaluator = DefaultTrustEvaluator() #endif

NEVER ignore response validation:

// ❌ Silently accepts 4xx/5xx as success session.request(endpoint) .responseDecodable(of: User.self) { response in // May decode error response as User! }

// ✅ Always validate before decoding session.request(endpoint) .validate(statusCode: 200..<300) .responseDecodable(of: User.self) { response in // Only called for 2xx responses }

Retry Logic

NEVER retry non-idempotent requests:

// ❌ May create duplicate orders func placeOrder() { session.request(APIRouter.createOrder) .validate() .response { response in if response.error != nil { self.placeOrder() // Retry — may duplicate! } } }

// ✅ Use idempotency keys for non-idempotent operations func placeOrder(idempotencyKey: String) { session.request(APIRouter.createOrder(idempotencyKey: idempotencyKey)) // Server uses key to prevent duplicates }

NEVER retry immediately without backoff:

// ❌ Hammers server during outage let retryPolicy = RetryPolicy(retryLimit: 5) // Immediate retries

// ✅ Exponential backoff let retryPolicy = RetryPolicy( retryLimit: 3, exponentialBackoffBase: 2, exponentialBackoffScale: 0.5 )

Essential Patterns

Authenticator with Refresh Coordination

final class OAuthAuthenticator: Authenticator { private let tokenStore: TokenStore private let refreshService: RefreshService

func apply(_ credential: OAuthCredential, to urlRequest: inout URLRequest) {
    urlRequest.headers.add(.authorization(bearerToken: credential.accessToken))
}

func refresh(_ credential: OAuthCredential, for session: Session, completion: @escaping (Result<OAuthCredential, Error>) -> Void) {
    // Alamofire ensures only ONE refresh happens
    // Other 401 requests wait for this to complete
    refreshService.refresh(refreshToken: credential.refreshToken) { result in
        switch result {
        case .success(let tokens):
            let newCredential = OAuthCredential(
                accessToken: tokens.accessToken,
                refreshToken: tokens.refreshToken,
                expiration: tokens.expiration
            )
            self.tokenStore.save(newCredential)
            completion(.success(newCredential))
        case .failure(let error):
            completion(.failure(error))
        }
    }
}

func didRequest(_ urlRequest: URLRequest, with response: HTTPURLResponse, failDueToAuthenticationError error: Error) -> Bool {
    response.statusCode == 401
}

func isRequest(_ urlRequest: URLRequest, authenticatedWith credential: OAuthCredential) -> Bool {
    urlRequest.headers["Authorization"] == "Bearer \(credential.accessToken)"
}

}

Compositor Interceptor

// Combine multiple adapters and retriers let interceptor = Interceptor( adapters: [ AuthAdapter(tokenStore: tokenStore), LoggingAdapter(), DeviceInfoAdapter() ], retriers: [ AuthRetrier(authenticator: authenticator), NetworkRetrier(retryLimit: 3) ] )

let session = Session(interceptor: interceptor)

Certificate Pinning

let evaluators: [String: ServerTrustEvaluating] = [ "api.yourapp.com": PinnedCertificatesTrustEvaluator( certificates: Bundle.main.af.certificates, acceptSelfSignedCertificates: false, performDefaultValidation: true, validateHost: true ) ]

let session = Session( serverTrustManager: ServerTrustManager(evaluators: evaluators) )

Quick Reference

When Alamofire Adds Value

Feature URLSession Alamofire

Basic REST ✅ Sufficient Overkill

Token refresh with retry Tricky ✅ Authenticator

Certificate pinning Possible ✅ Cleaner API

Request/Response logging Custom ✅ EventMonitor

Multipart upload progress Verbose ✅ Clean API

Connection pooling Automatic Automatic

Interceptor Checklist

• Single Session instance shared across app

• Authenticator for token refresh (not generic retry)

• Exponential backoff for transient failures

• Only retry idempotent requests

• Validate responses before decoding

• Certificate pinning for production

Red Flags

Smell Problem Fix

New Session per request Loses pooling Share Session

DisabledTrustEvaluator in prod Security hole Proper pinning

Token refresh in RetryPolicy Race condition Use Authenticator

Retry without backoff Server hammering Exponential backoff

No .validate() call Silent failures Always validate

Complex conditionals in Interceptor Wrong layer Router pattern