home / skills / hoangnguyen0403 / agent-skills-standard / networking

networking skill

safe

This skill helps you implement iOS networking standards with URLSession and Alamofire while enforcing Codable, retries, and secure practices.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill networking

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.7 KB

---
name: iOS Networking
description: Standards for URLSession, Alamofire, and API communication.
metadata:
  labels: [ios, networking, urlsession, alamofire, codable]
  triggers:
    files: ['**/*Service.swift', '**/*API.swift', '**/*Client.swift']
    keywords: [URLSession, Alamofire, Moya, URLRequest, URLComponents, Codable]
---

# iOS Networking Standards

## **Priority: P0**

## Implementation Guidelines

### URLSession (Native)

- **Tasks**: Use `dataTaskPublisher` (Combine) or `data(for:delegate:)` (async/await).
- **Configuration**: Use `URLSessionConfiguration.default` for standard tasks and `ephemeral` for private browsing/clearing cache.
- **Request Building**: Use `URLComponents` and `URLQueryItem` to build URLs safely. Never use string interpolation for parameters.

### Alamofire (Standard Third-Party)

- **Session**: Maintain a singleton or DI-injected `Session` instance.
- **Request**: Use `.validate()` to automatically check for 200..299 status codes.
- **Encoding**: Use `JSONParameterEncoder.default` for body parameters.

### Best Practices

- **Codable**: Use `Codable` for JSON mapping. Prefer `snake_case` to `camelCase` decoding strategies if the API follows snake_case.
- **Retriers & Adapters**: Use `RequestInterceptor` for adding Auth headers (Bearer) and handling token refresh (401).
- **SSL Pinning**: Implement using `ServerTrustManager` for production security.

## Anti-Patterns

- **Main Thread completion**: `**No UI updates in background task**: Always jump to Main thread/MainActor.`
- **Raw Mapping**: `**No manual JSONSerialization**: Use Codable.`
- **Missing Timeout**: `**No indefinite wait**: Always set a reasonable timeoutInterval (e.g., 30s).`

## References

- [Native & Alamofire Implementation](references/implementation.md)

Overview

This skill documents iOS networking standards covering native URLSession and the Alamofire library. It focuses on safe request construction, configuration choices, error handling, and common anti-patterns to keep network code robust and secure. The guidance is practical and implementation-oriented for Swift projects.

How this skill works

The skill prescribes using modern APIs: Combine's dataTaskPublisher or async/await data(for:delegate:) for URLSession and a singleton or DI-managed Session for Alamofire. It enforces safe URL construction with URLComponents/URLQueryItem, JSON encoding/decoding with Codable, and automatic response validation and retries via Alamofire utilities and RequestInterceptor patterns. Security measures like SSL pinning and centralized auth handling are described for production readiness.

When to use it

Building HTTP clients for iOS apps that require predictable, testable networking.
Choosing between native URLSession and Alamofire depending on project complexity and team familiarity.
Implementing token-based authentication with automatic refresh on 401 responses.
Handling background tasks where Combine or async/await patterns fit naturally.
Enforcing consistent JSON mapping and decoding strategies across the app.

Best practices

Use URLComponents and URLQueryItem to assemble URLs; avoid string interpolation for parameters.
Prefer Codable for JSON mapping and set keyDecodingStrategy to snake_case if the API uses snake_case.
Keep a single Session instance (singleton or DI) for Alamofire and call .validate() on requests.
Implement RequestInterceptor to add Authorization headers and handle token refresh centrally.
Set explicit timeoutInterval (e.g., 30s) and avoid blocking UI updates from background threads.
Use ServerTrustManager (SSL pinning) in production to reduce MITM risk.

Example use cases

Fetching REST API data with async/await using URLSession and Codable models.
Uploading JSON payloads with Alamofire using JSONParameterEncoder.default and response validation.
Automatic token renewal via a RequestInterceptor when an API returns 401 Unauthorized.
Temporary ephemeral URLSessionConfiguration for private browsing or sensitive request flows.
Implementing retries and backoff for intermittent network failures with an Alamofire retrier.

FAQ

When should I prefer URLSession over Alamofire?

Use URLSession for lightweight needs, minimal dependencies, and when you want tight control; choose Alamofire for convenience, built-in validation, and richer tooling like interceptors and encoders.

How do I safely add query parameters?

Always use URLComponents and URLQueryItem to encode parameters. This avoids encoding bugs and injection risks compared to string concatenation.