Most modern iOS applications need to communicate with the internet.

A weather app needs weather data.

An eCommerce app needs products and orders.

A social media app needs posts and profiles.

A news application needs articles.

A login screen may need to send credentials to a server.

All of these features require network communication.

In Swift, one of the most important APIs for networking is:

URLSession

URLSession is Apple’s networking API for sending HTTP requests, receiving responses, downloading files, uploading data, and communicating with web services.

In this complete guide, you will learn URLSession from beginner concepts to practical API integration using modern Swift.

We will cover:

What URLSession is
How HTTP requests work
GET requests
async/await
URLRequest
HTTP methods
Headers
Status codes
Codable
JSON decoding
POST requests
PUT, PATCH, and DELETE
Error handling
Authentication headers
Query parameters
Reusable API clients
File downloads
Uploads
Cancellation
Timeouts
SwiftUI integration
Testing
Common mistakes
Production best practices

What Is URLSession in Swift?

URLSession is a Foundation API used by Swift applications to communicate with resources identified by URLs.

In simple terms:

URLSession allows your Swift application to send requests to servers and receive responses.

A common network flow looks like:

iOS App
   ↓
URLSession
   ↓
HTTP Request
   ↓
REST API
   ↓
Server
   ↓
JSON Response
   ↓
Swift Model
   ↓
SwiftUI

For example, your app might request:

GET /users

The server could return:

[
  {
    "id": 1,
    "name": "Alex"
  },
  {
    "id": 2,
    "name": "Emma"
  }
]

Swift can decode that JSON into strongly typed models.

Why Is URLSession Important?

Many real applications depend on remote data.

You may need networking for:

Authentication
User profiles
Product catalogs
Search
Payments
Notifications
Social feeds
Chat history
News
Weather
Maps-related backend data
File uploads
Image downloads
Cloud synchronization

Understanding URLSession therefore gives you a foundation for building API-driven iOS applications.

Import Foundation

URLSession is part of Foundation.

Start with:

import Foundation

Foundation also provides many related types, including:

URL
URLRequest
URLResponse
HTTPURLResponse
JSONDecoder
JSONEncoder
Data
URLComponents

Understanding HTTP Before URLSession

Before writing networking code, understand the basic client-server relationship.

Your iOS application acts as a client.

iPhone App
    ↓
HTTP Request
    ↓
Server
    ↓
HTTP Response
    ↓
iPhone App

A request generally contains:

URL
HTTP Method
Headers
Body
Query Parameters

The response generally contains:

Status Code
Headers
Response Body

Common HTTP Methods

The most common methods are:

Method	Typical Purpose
GET	Retrieve data
POST	Create/send data
PUT	Replace/update data
PATCH	Partially update data
DELETE	Delete data

For example:

GET /users

retrieves users.

POST /users

creates a user.

PATCH /users/10

updates part of user 10.

DELETE /users/10

deletes user 10.

Your First URLSession Request

Modern Swift networking works very well with async/await.

A simple request looks like:

import Foundation

func loadData() async throws {

    let url = URL(
        string: "https://example.com/api/users"
    )!

    let (data, response) =
        try await URLSession.shared.data(
            from: url
        )

    print(data)
    print(response)
}

The key line is:

try await URLSession.shared.data(from: url)

It performs the network request asynchronously.

What Is URLSession.shared?

This:

URLSession.shared

provides a shared session configured for common networking tasks.

For simple requests, it is often enough.

Example:

let (data, response) =
    try await URLSession.shared.data(
        from: url
    )

For applications requiring custom:

Timeouts
Caching
Cookie behavior
Connectivity settings
Session configuration

you can create your own URLSession.

Understanding async and await

Network requests take time.

The server might respond in:

100 ms
500 ms
2 seconds
10 seconds

You should not block the UI while waiting.

Swift concurrency lets you write:

func fetchUsers() async throws {
    // asynchronous work
}

Then:

try await fetchUsers()

await indicates that execution may suspend while waiting for asynchronous work to complete.

The UI thread does not need to remain blocked during that wait.

What Does `throws` Mean?

Network operations can fail.

Possible reasons include:

No internet
DNS failure
Timeout
Server unavailable
Invalid URL
Connection interruption

Therefore, networking functions often use:

throws

Example:

func fetchData() async throws {
}

Calling the function requires:

try await fetchData()

Errors can then be handled with do-catch.

Handling URLSession Errors

Example:

do {

    let (data, response) =
        try await URLSession.shared.data(
            from: url
        )

    print(data)
    print(response)

} catch {

    print(
        "Request failed:",
        error
    )
}

This handles transport-level errors thrown by URLSession.

However, this alone is not enough for production networking.

You must also inspect the HTTP response.

Understanding HTTPURLResponse

URLSession returns:

URLResponse

For HTTP requests, cast it to:

HTTPURLResponse

Example:

guard let httpResponse =
    response as? HTTPURLResponse
else {
    throw APIError.invalidResponse
}

Now you can access:

httpResponse.statusCode

Understanding HTTP Status Codes

Common status codes include:

Code	Meaning
200	OK
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Validation error
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

A common success check is:

guard (200...299).contains(
    httpResponse.statusCode
) else {

    throw APIError.badStatusCode(
        httpResponse.statusCode
    )
}

Do not assume that receiving data means the request succeeded.

A server can return JSON along with a 404 or 500 response.

Creating Custom API Errors

Create an error type:

enum APIError: Error {

    case invalidURL
    case invalidResponse
    case badStatusCode(Int)
    case decodingFailed
}

Now your networking code can communicate failures more clearly.

Complete Basic GET Request

import Foundation

enum APIError: Error {

    case invalidURL
    case invalidResponse
    case badStatusCode(Int)
}

func fetchUsers() async throws -> Data {

    guard let url = URL(
        string: "https://example.com/api/users"
    ) else {
        throw APIError.invalidURL
    }

    let (data, response) =
        try await URLSession.shared.data(
            from: url
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    ) else {

        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }

    return data
}

This is already much safer than blindly trusting the response.

JSON and URLSession

Most modern REST APIs return JSON.

Example:

{
  "id": 1,
  "name": "Alex",
  "email": "alex@example.com"
}

Instead of manually reading JSON dictionaries, Swift can convert this data into models using Codable.

Creating a Codable Model

struct User: Codable {

    let id: Int
    let name: String
    let email: String
}

Now JSON can be decoded using:

JSONDecoder()

Decoding JSON

let user =
    try JSONDecoder().decode(
        User.self,
        from: data
    )

The flow becomes:

JSON Data
   ↓
JSONDecoder
   ↓
User.self
   ↓
Swift User Object

Complete GET Request with Codable

func fetchUser() async throws -> User {

    guard let url = URL(
        string: "https://example.com/api/user/1"
    ) else {
        throw APIError.invalidURL
    }

    let (data, response) =
        try await URLSession.shared.data(
            from: url
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    ) else {

        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }

    return try JSONDecoder().decode(
        User.self,
        from: data
    )
}

This is a common Swift networking pattern.

Decoding an Array

Suppose the API returns:

[
  {
    "id": 1,
    "name": "Alex",
    "email": "alex@example.com"
  },
  {
    "id": 2,
    "name": "Emma",
    "email": "emma@example.com"
  }
]

Decode:

let users =
    try JSONDecoder().decode(
        [User].self,
        from: data
    )

Notice:

[User].self

because the response is an array.

Handling Different JSON Keys

Suppose the API returns:

{
  "user_id": 1,
  "full_name": "Alex Smith"
}

but your Swift model uses:

struct User: Codable {

    let userID: Int
    let fullName: String
}

You can define coding keys:

struct User: Codable {

    let userID: Int
    let fullName: String

    enum CodingKeys: String, CodingKey {

        case userID = "user_id"
        case fullName = "full_name"
    }
}

Convert Snake Case Automatically

If the backend consistently uses snake_case:

{
  "user_id": 1,
  "full_name": "Alex"
}

you can configure:

let decoder = JSONDecoder()

decoder.keyDecodingStrategy =
    .convertFromSnakeCase

Then decode:

let user =
    try decoder.decode(
        User.self,
        from: data
    )

This can reduce manual coding keys.

What Is URLRequest?

For simple GET requests, this works:

URLSession.shared.data(
    from: url
)

But real APIs often require:

HTTP methods
Headers
Authorization
Request bodies
Timeout settings

For this, use:

URLRequest

Creating a URLRequest

var request =
    URLRequest(url: url)

request.httpMethod = "GET"

You can now configure the request before sending it.

Send it with:

let (data, response) =
    try await URLSession.shared.data(
        for: request
    )

Notice the difference:

data(from: url)

vs:

data(for: request)

The second gives you more control.

Adding HTTP Headers

Headers provide metadata about the request.

Example:

request.setValue(
    "application/json",
    forHTTPHeaderField:
        "Content-Type"
)

Another common header:

request.setValue(
    "application/json",
    forHTTPHeaderField:
        "Accept"
)

Authorization Header

Many APIs use bearer tokens.

Example:

let token = "your_access_token"

request.setValue(
    "Bearer \(token)",
    forHTTPHeaderField:
        "Authorization"
)

The resulting HTTP header conceptually looks like:

Authorization: Bearer your_access_token

Never hard-code production secrets into your iOS application.

GET Request with Headers

func fetchProfile(
    token: String
) async throws -> User {

    guard let url = URL(
        string:
            "https://example.com/api/profile"
    ) else {
        throw APIError.invalidURL
    }

    var request =
        URLRequest(url: url)

    request.httpMethod = "GET"

    request.setValue(
        "Bearer \(token)",
        forHTTPHeaderField:
            "Authorization"
    )

    request.setValue(
        "application/json",
        forHTTPHeaderField:
            "Accept"
    )

    let (data, response) =
        try await URLSession.shared.data(
            for: request
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    ) else {

        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }

    return try JSONDecoder().decode(
        User.self,
        from: data
    )
}

Query Parameters

Suppose you need:

/products?page=1&limit=20&search=iphone

Avoid manually concatenating complex query strings.

Use:

URLComponents

Example:

var components =
    URLComponents(
        string:
            "https://example.com/api/products"
    )

components?.queryItems = [

    URLQueryItem(
        name: "page",
        value: "1"
    ),

    URLQueryItem(
        name: "limit",
        value: "20"
    ),

    URLQueryItem(
        name: "search",
        value: "iphone"
    )
]

guard let url = components?.url else {
    throw APIError.invalidURL
}

This correctly handles URL encoding.

Why URLComponents Is Better

Imagine a search:

iPhone 17 Pro

Spaces and special characters need proper encoding.

URLComponents helps construct valid URLs safely.

Avoid:

let url =
    URL(
        string:
            "https://example.com/search?q=\(searchText)"
    )

when arbitrary user input is involved.

Making a POST Request

POST requests commonly send data to a server.

Examples:

Registration
Login
Create task
Create order
Submit form
Add comment

Suppose the API expects:

{
  "name": "Alex",
  "email": "alex@example.com"
}

Create a request model.

struct CreateUserRequest: Encodable {

    let name: String
    let email: String
}

Encode Swift Model to JSON

Use:

JSONEncoder()

Example:

let body =
    CreateUserRequest(
        name: "Alex",
        email: "alex@example.com"
    )

let jsonData =
    try JSONEncoder().encode(body)

Now:

jsonData

can become the HTTP request body.

Complete POST Request

func createUser(
    name: String,
    email: String
) async throws -> User {

    guard let url = URL(
        string:
            "https://example.com/api/users"
    ) else {
        throw APIError.invalidURL
    }

    var request =
        URLRequest(url: url)

    request.httpMethod = "POST"

    request.setValue(
        "application/json",
        forHTTPHeaderField:
            "Content-Type"
    )

    let body =
        CreateUserRequest(
            name: name,
            email: email
        )

    request.httpBody =
        try JSONEncoder().encode(body)

    let (data, response) =
        try await URLSession.shared.data(
            for: request
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    ) else {

        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }

    return try JSONDecoder().decode(
        User.self,
        from: data
    )
}

This demonstrates a complete JSON POST request.

PUT Request

PUT is commonly used to replace or update a resource.

request.httpMethod = "PUT"

Example:

PUT /users/10

with body:

{
  "name": "Updated Name",
  "email": "new@example.com"
}

The exact semantics depend on the API design.

PATCH Request

PATCH is commonly used for partial updates.

request.httpMethod = "PATCH"

For example:

PATCH /users/10

Body:

{
  "name": "New Name"
}

Only the supplied field may be updated.

Again, follow the backend API contract.

DELETE Request

func deleteUser(
    id: Int
) async throws {

    guard let url = URL(
        string:
            "https://example.com/api/users/\(id)"
    ) else {
        throw APIError.invalidURL
    }

    var request =
        URLRequest(url: url)

    request.httpMethod = "DELETE"

    let (_, response) =
        try await URLSession.shared.data(
            for: request
        )

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    guard (200...299).contains(
        httpResponse.statusCode
    ) else {

        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }
}

Some DELETE endpoints return JSON.

Others return:

204 No Content

Your decoding logic must match the API contract.

Never Decode an Empty Response Blindly

Suppose the server returns:

204 No Content

Then this may fail:

try JSONDecoder().decode(
    User.self,
    from: data
)

because there is nothing to decode.

Always understand what each endpoint returns.

Better APIError Design

A more useful error type might be:

enum APIError: Error {

    case invalidURL

    case invalidResponse

    case unauthorized

    case forbidden

    case notFound

    case serverError

    case badStatusCode(Int)

    case decoding(Error)
}

Then status codes can be mapped appropriately.

Mapping HTTP Status Codes

func validate(
    _ response: URLResponse
) throws {

    guard let httpResponse =
        response as? HTTPURLResponse
    else {
        throw APIError.invalidResponse
    }

    switch httpResponse.statusCode {

    case 200...299:
        return

    case 401:
        throw APIError.unauthorized

    case 403:
        throw APIError.forbidden

    case 404:
        throw APIError.notFound

    case 500...599:
        throw APIError.serverError

    default:
        throw APIError.badStatusCode(
            httpResponse.statusCode
        )
    }
}

Now response validation can be reused.

Handling Decoding Errors

JSON decoding can fail because:

Property missing
Wrong type
Invalid JSON
Wrong nesting
Incorrect date format
Incorrect model

Handle it separately:

do {

    return try JSONDecoder().decode(
        User.self,
        from: data
    )

} catch {

    throw APIError.decoding(error)
}

During development, inspect the original error carefully.

DecodingError often tells you exactly which field caused the problem.

Debugging JSON Responses

During development, it can be useful to inspect raw JSON.

if let jsonString =
    String(
        data: data,
        encoding: .utf8
    ) {

    print(jsonString)
}

This can help identify:

Wrong endpoint
Error response
Unexpected JSON shape
Missing fields

Be careful not to log sensitive production information such as access tokens, passwords, or private user data.

Date Decoding

Suppose an API returns:

{
  "createdAt": "2026-09-01T10:30:00Z"
}

Your model might use:

struct Post: Decodable {

    let createdAt: Date
}

Configure:

let decoder = JSONDecoder()

decoder.dateDecodingStrategy =
    .iso8601

Then:

let post =
    try decoder.decode(
        Post.self,
        from: data
    )

Date formats must match what the backend actually sends.

Creating a Reusable API Client

Copying the same URLSession logic into every screen is a common beginner mistake.

Instead of:

LoginView → URLSession
HomeView → URLSession
ProfileView → URLSession
ProductView → URLSession

prefer:

Views
  ↓
Feature Models
  ↓
Services / Repositories
  ↓
APIClient
  ↓
URLSession

Generic API Client

Here is a simplified reusable client:

final class APIClient {

    private let session: URLSession

    init(
        session: URLSession = .shared
    ) {

        self.session = session
    }

    func send<T: Decodable>(
        _ request: URLRequest,
        as type: T.Type
    ) async throws -> T {

        let (data, response) =
            try await session.data(
                for: request
            )

        try validate(response)

        do {

            return try JSONDecoder().decode(
                T.self,
                from: data
            )

        } catch {

            throw APIError.decoding(error)
        }
    }

    private func validate(
        _ response: URLResponse
    ) throws {

        guard let httpResponse =
            response as? HTTPURLResponse
        else {
            throw APIError.invalidResponse
        }

        guard (200...299).contains(
            httpResponse.statusCode
        ) else {

            throw APIError.badStatusCode(
                httpResponse.statusCode
            )
        }
    }
}

Now different services can reuse the same networking logic.

Using the Generic API Client

let client = APIClient()

let users: [User] =
    try await client.send(
        request,
        as: [User].self
    )

For one user:

let user: User =
    try await client.send(
        request,
        as: User.self
    )

Generics help reduce duplicated decoding code.

Create an Endpoint Type

Larger projects can represent API endpoints explicitly.

enum Endpoint {

    case users
    case user(Int)
    case profile

    var path: String {

        switch self {

        case .users:
            return "/users"

        case .user(let id):
            return "/users/\(id)"

        case .profile:
            return "/profile"
        }
    }
}

Then construct URLs from:

Base URL
+
Endpoint Path

For example:

https://api.example.com
+
/users

Avoid Repeating Base URLs

Bad:

"https://api.example.com/users"

"https://api.example.com/profile"

"https://api.example.com/products"

Better:

enum APIConfig {

    static let baseURL =
        "https://api.example.com"
}

Then construct endpoints from one source.

For production apps, environment-specific configuration may be more appropriate.

Development vs Production APIs

Real projects may have different environments.

Development
https://dev-api.example.com

Staging
https://staging-api.example.com

Production
https://api.example.com

Do not scatter these URLs throughout the application.

Centralize environment configuration.

URLSession Configuration

Instead of always using:

URLSession.shared

you can create a custom session.

let configuration =
    URLSessionConfiguration.default

configuration.timeoutIntervalForRequest =
    30

configuration.timeoutIntervalForResource =
    60

let session =
    URLSession(
        configuration: configuration
    )

This gives you more control over networking behavior.

Request Timeout

You can also configure a request:

var request =
    URLRequest(url: url)

request.timeoutInterval = 30

Timeout values should match the expected behavior of your API and user experience.

Caching

HTTP caching can improve:

Performance
Data usage
Loading speed

URLSession can work with:

URLCache
Cache-Control headers
Request cache policies

Example:

request.cachePolicy =
    .returnCacheDataElseLoad

However, caching should follow your application’s data freshness requirements.

Do not cache everything blindly.

URLSession and Authentication

A typical authenticated request looks like:

Login
 ↓
Server
 ↓
Access Token
 ↓
Secure Storage
 ↓
Authorization Header
 ↓
Authenticated API

Request:

request.setValue(
    "Bearer \(token)",
    forHTTPHeaderField:
        "Authorization"
)

Tokens should be handled securely.

Sensitive credentials should not simply be stored in plain text.

Never Put API Secrets in an iOS App

Anything shipped inside a client application can potentially be inspected.

Do not embed sensitive server secrets such as:

Database passwords
Private API secrets
Payment secret keys
Backend signing secrets
Admin credentials

inside your iOS application.

Client apps should receive only credentials that are safe for client-side use.

Sensitive operations belong on secure backend infrastructure.

Token Refresh

Many authentication systems use:

Access Token
+
Refresh Token

Typical flow:

Request
  ↓
401 Unauthorized
  ↓
Refresh Access Token
  ↓
Retry Request

A production API layer may centralize this behavior instead of repeating it across every screen.

Be careful with simultaneous refresh attempts and retry loops.

Downloading a File

URLSession provides download APIs.

Example:

func downloadFile(
    from url: URL
) async throws -> URL {

    let (
        temporaryURL,
        response
    ) =
        try await URLSession.shared.download(
            from: url
        )

    try validateDownloadResponse(
        response
    )

    return temporaryURL
}

The returned file URL may point to a temporary location.

If you need the file later, move it to an appropriate application directory.

Downloading an Image as Data

For smaller resources:

let (data, response) =
    try await URLSession.shared.data(
        from: imageURL
    )

Then UIKit could create:

let image =
    UIImage(data: data)

For production image-heavy applications, consider:

Caching
Request cancellation
Memory management
Downsampling
Reusable image-loading infrastructure

Uploading Data

URLSession also supports uploads.

A simple data upload can use:

let (data, response) =
    try await URLSession.shared.upload(
        for: request,
        from: uploadData
    )

The request must be configured according to the backend’s expected content type.

Multipart Form Data

Image and file upload APIs often expect:

multipart/form-data

A multipart request contains boundaries separating:

Text fields
File metadata
File bytes

Conceptually:

Multipart Body
│
├── name
├── description
└── image.jpg

Multipart encoding is more involved than JSON encoding, so many production applications create a dedicated multipart builder.

Always follow the backend API specification.

URLSessionDataTask and Completion Handlers

Before async/await became the preferred modern approach, URLSession commonly used completion handlers.

Example:

URLSession.shared.dataTask(
    with: url
) { data, response, error in

    if let error {
        print(error)
        return
    }

    guard let data else {
        return
    }

    print(data)

}.resume()

The important part is:

.resume()

A newly created data task does not begin until resumed.

Completion Handler vs async/await

Older style:

URLSession.shared.dataTask(
    with: url
) { data, response, error in

}
.resume()

Modern style:

let (data, response) =
    try await URLSession.shared.data(
        from: url
    )

Async/await often provides:

Easier reading
Cleaner control flow
Better error propagation
Less nested code
Easier composition

You should still recognize completion-handler networking because many existing iOS projects use it.

Cancelling a Network Request

Swift concurrency tasks can be cancelled.

Example:

let task = Task {

    try await fetchUsers()
}

Later:

task.cancel()

Cancellation is useful for situations such as:

Search suggestions
Screen disappearing
User changing filters
Repeated requests

Search Request Cancellation

Imagine:

User types "i"
↓
Request 1

User types "ip"
↓
Request 2

User types "iphone"
↓
Request 3

You may not want all old requests to continue.

A better system can:

Cancel Previous Request
       ↓
Start Latest Request

This saves resources and helps prevent stale results.

URLSession in SwiftUI

Networking is often connected to SwiftUI through an observable model.

Example:

import Observation

@MainActor
@Observable
final class UserViewModel {

    var users: [User] = []

    var isLoading = false

    var errorMessage: String?

    func loadUsers() async {

        isLoading = true
        errorMessage = nil

        defer {
            isLoading = false
        }

        do {

            users =
                try await UserService()
                    .fetchUsers()

        } catch {

            errorMessage =
                error.localizedDescription
        }
    }
}

The view can display the state.

SwiftUI View Example

struct UserListView: View {

    @State
    private var viewModel =
        UserViewModel()

    var body: some View {

        NavigationStack {

            Group {

                if viewModel.isLoading {

                    ProgressView()

                } else if let message =
                    viewModel.errorMessage {

                    Text(message)

                } else {

                    List(
                        viewModel.users
                    ) { user in

                        Text(user.name)
                    }
                }
            }
            .navigationTitle("Users")
            .task {

                await viewModel.loadUsers()
            }
        }
    }
}

This creates the flow:

View Appears
    ↓
.task
    ↓
ViewModel
    ↓
Service
    ↓
URLSession
    ↓
API
    ↓
Decoded Models
    ↓
State Changes
    ↓
SwiftUI Updates

Better Loading State

Instead of several independent variables:

var isLoading = false
var errorMessage: String?
var users: [User] = []

you can model screen state explicitly.

enum LoadState {

    case idle
    case loading
    case loaded([User])
    case failed(String)
}

Then:

var state: LoadState = .idle

This prevents contradictory UI states.

Pagination

Large APIs should not always return every record at once.

Example:

GET /products?page=1&limit=20

Then:

Page 1 → 20 items
Page 2 → next 20
Page 3 → next 20

SwiftUI can load additional data as the user approaches the end of a list.

A ViewModel might track:

var currentPage = 1
var isLoadingMore = false
var hasMorePages = true

Pagination requires careful duplicate-request handling.

Retry Logic

Some temporary failures can be retried.

Examples:

Temporary connectivity issue
Certain server errors
Rate-limit handling when instructed by the server

But avoid infinite retries.

Bad:

Request fails
↓
Retry
↓
Fails
↓
Retry forever

Better:

Attempt
↓
Temporary Failure
↓
Limited Retry
↓
Backoff
↓
Eventually Stop

Only retry operations when doing so is safe.

Exponential Backoff

A retry strategy may wait increasingly longer:

Attempt 1
↓
Wait 1 second

Attempt 2
↓
Wait 2 seconds

Attempt 3
↓
Wait 4 seconds

This helps avoid repeatedly overwhelming a failing service.

Production retry strategies should also consider server guidance such as Retry-After.

Network Reachability

Do not assume that checking network status guarantees a request will succeed.

Network conditions can change instantly.

A better principle is:

Attempt the request and handle failure correctly.

Reachability information can still help improve UI behavior, but it should not replace robust request error handling.

Handling Offline Mode

Applications requiring offline support may use:

Local Database
      ↓
Cached Data
      ↓
UI
      ↓
Network Available?
      ↓
Synchronize

URLSession handles networking.

Offline architecture requires additional storage and synchronization logic.

URLSession and HTTPS

Production APIs should generally use secure HTTPS connections.

Example:

https://api.example.com

instead of insecure HTTP.

Apple platforms also enforce transport security policies that encourage secure connections.

Do not disable security protections globally simply to make an insecure endpoint work.

Fix the server configuration whenever possible.

App Transport Security

Apple’s App Transport Security policies encourage secure network connections.

If an API uses outdated or insecure networking configuration, your application may encounter connection problems.

Avoid broad ATS exceptions unless there is a legitimate and carefully evaluated requirement.

HTTP Headers You Should Know

Common headers include:

Content-Type
Accept
Authorization
User-Agent
Cache-Control
ETag
If-None-Match

Example:

request.setValue(
    "application/json",
    forHTTPHeaderField:
        "Content-Type"
)

The correct headers depend on the API.

Content-Type vs Accept

These are often confused.

Content-Type describes the format of the request body.

Example:

Content-Type: application/json

means:

I am sending JSON.

Accept indicates which response format the client expects.

Accept: application/json

means:

I would like JSON back.

URLSession Delegate

For advanced networking behavior, URLSession can use delegates.

Delegates can help with:

Authentication challenges
Redirect handling
Progress tracking
Background sessions
Custom session events

For basic API calls, you may not need a delegate.

For advanced networking, understanding URLSessionDelegate and task-specific delegates becomes important.

Background Downloads

Large downloads may need to continue even when the app is not actively in the foreground.

URLSession supports background session configurations.

Conceptually:

App
 ↓
Background URLSession
 ↓
System Manages Transfer
 ↓
App Receives Completion

This is different from ordinary short API requests.

Testing URLSession Code

Networking code becomes easier to test when URLSession is injected instead of hard-coded everywhere.

Instead of:

URLSession.shared

inside every function, use:

private let session: URLSession

Then:

init(
    session: URLSession = .shared
) {
    self.session = session
}

This makes it easier to provide a controlled session during tests.

Protocol-Based Networking

You can make networking even more testable.

protocol NetworkClient {

    func send<T: Decodable>(
        _ request: URLRequest,
        as type: T.Type
    ) async throws -> T
}

Your production API client implements it.

Tests can provide a mock.

Conceptually:

ViewModel
   ↓
NetworkClient Protocol
   ↓
------------------------
↓                      ↓
Real APIClient       MockClient

This reduces coupling.

API Service Example

protocol UserServiceProtocol {

    func fetchUsers()
        async throws -> [User]
}

Implementation:

final class UserService:
    UserServiceProtocol {

    private let client: APIClient

    init(
        client: APIClient =
            APIClient()
    ) {

        self.client = client
    }

    func fetchUsers()
        async throws -> [User] {

        let url =
            URL(
                string:
                    "\(APIConfig.baseURL)/users"
            )!

        let request =
            URLRequest(url: url)

        return try await client.send(
            request,
            as: [User].self
        )
    }
}

Now the UI does not need to know how URLSession works internally.

Real-World Networking Architecture

A scalable project may look like:

SwiftUI View
     ↓
ViewModel
     ↓
Repository
     ↓
API Service
     ↓
API Client
     ↓
URLSession
     ↓
REST API

Each layer has a responsibility.

View

Displays data.

ViewModel

Coordinates UI state and actions.

Repository

Coordinates data sources when needed.

API Service

Defines feature-specific API operations.

API Client

Handles generic HTTP networking.

URLSession

Performs the actual network transport.

You do not need all layers for every small app.

Add architecture as complexity grows.

Common Mistake: Force-Unwrapping URLs

Avoid:

let url =
    URL(
        string: apiURL
    )!

when the URL is dynamic.

Better:

guard let url =
    URL(
        string: apiURL
    )
else {
    throw APIError.invalidURL
}

Static developer-controlled URLs may sometimes be force-unwrapped during development, but robust code should treat dynamic URL construction carefully.

Common Mistake: Ignoring Status Codes

This is incomplete:

let (data, _) =
    try await URLSession.shared.data(
        from: url
    )

You should usually validate the HTTP response.

Otherwise:

404
401
500

may incorrectly continue into normal decoding logic.

Common Mistake: Using try?

Avoid hiding useful networking errors unnecessarily.

let user =
    try? JSONDecoder().decode(
        User.self,
        from: data
    )

If decoding fails, you may lose valuable debugging information.

Prefer proper do-catch or error propagation.

Common Mistake: Logging Tokens

Avoid:

print(token)

in production.

Also avoid logging:

Passwords
Authorization headers
Payment data
Personal information
Sensitive API responses

Development logs often accidentally survive longer than expected.

Common Mistake: Networking Directly in SwiftUI body

Do not perform network requests directly while computing:

var body: some View

SwiftUI may evaluate body repeatedly.

Use appropriate lifecycle mechanisms such as:

.task {
    await viewModel.loadUsers()
}

and move networking logic into a service or model.

Common Mistake: One Huge NetworkManager

A beginner project may start with:

NetworkManager.swift

and eventually place every API endpoint into one 5,000-line class.

Instead, separate responsibilities.

For example:

APIClient
├── AuthenticationService
├── UserService
├── ProductService
├── OrderService
└── PaymentService

This improves maintainability.

Common Mistake: Hard-Coding Everything

Avoid scattering:

Base URLs
Tokens
Headers
Endpoint paths
Timeouts
Environment values

throughout views.

Centralize configuration appropriately.

Common Mistake: Treating Every Error the Same

A user should not necessarily see:

The operation couldn't be completed.
NSURLErrorDomain Code=-1009

Create user-friendly error messages.

For example:

No internet connection.
Please check your connection and try again.

while retaining detailed diagnostic information for development and logging systems.

Production Networking Checklist

Before considering an API layer production-ready, check:

URLs are constructed safely
HTTPS is used
HTTP methods are correct
Headers are correct
Authentication is secure
Status codes are validated
JSON decoding errors are handled
Timeouts are configured appropriately
Requests can be cancelled where useful
Loading states are displayed
Empty states are handled
Error states are user-friendly
Sensitive information is not logged
API code is separated from views
Environment configuration is centralized
Networking is testable
Pagination is implemented when necessary
Retry logic is bounded
Token refresh is handled safely when required

URLSession Cheat Sheet

Simple GET

let (data, response) =
    try await URLSession.shared.data(
        from: url
    )

Custom Request

var request =
    URLRequest(url: url)

request.httpMethod = "GET"

Send URLRequest

let (data, response) =
    try await URLSession.shared.data(
        for: request
    )

JSON Header

request.setValue(
    "application/json",
    forHTTPHeaderField:
        "Content-Type"
)

Bearer Token

request.setValue(
    "Bearer \(token)",
    forHTTPHeaderField:
        "Authorization"
)

Decode JSON

let user =
    try JSONDecoder().decode(
        User.self,
        from: data
    )

Encode JSON

let data =
    try JSONEncoder().encode(
        requestModel
    )

Check Status Code

guard let response =
    response as? HTTPURLResponse,
      (200...299).contains(
        response.statusCode
      )
else {
    throw APIError.invalidResponse
}

Frequently Asked Questions

What is URLSession in Swift?

URLSession is Apple’s networking API for making HTTP requests, receiving responses, downloading files, uploading data, and communicating with remote services.

Is URLSession used for REST APIs?

Yes.

URLSession is commonly used to communicate with REST APIs from iOS applications.

Do I need a third-party library for networking in Swift?

Not necessarily.

URLSession is capable of handling many production networking requirements directly.

Third-party libraries can provide additional abstractions or conveniences, but they are not required for basic or even many advanced networking tasks.

Does URLSession support async/await?

Yes.

Modern URLSession APIs work with Swift concurrency.

For example:

let (data, response) =
    try await URLSession.shared.data(
        from: url
    )

What is the difference between data(from:) and data(for:)?

data(from:) is convenient when you only need a URL.

data(from: url)

data(for:) accepts a URLRequest, giving you more control over:

HTTP method
Headers
Body
Request configuration

What is URLRequest?

URLRequest represents a configurable network request.

It can contain:

URL
HTTP Method
Headers
Body
Timeout
Cache Policy

How do I parse JSON with URLSession?

URLSession gives you Data.

Then use:

JSONDecoder

to convert the data into a Decodable model.

How do I send JSON?

Create an Encodable model and use:

JSONEncoder

Then assign the resulting data to:

request.httpBody

How do I add an authorization token?

Usually:

request.setValue(
    "Bearer \(token)",
    forHTTPHeaderField:
        "Authorization"
)

The exact authentication scheme depends on the API.

Should I use URLSession.shared?

For straightforward requests, it can be perfectly adequate.

For applications requiring custom timeout, caching, session, delegate, or background behavior, create a configured URLSession.

Should networking code be inside SwiftUI views?

Small demonstrations may do this, but production applications generally benefit from separating networking into services, repositories, API clients, or observable feature models.

Can URLSession upload images?

Yes.

URLSession supports uploads.

Many image upload APIs use multipart/form-data, while others may accept raw binary data or encoded content.

Follow your backend’s API specification.

Can URLSession download files?

Yes.

Use download APIs when working with file transfers, especially when you want a temporary file URL rather than loading the entire resource directly into memory.

Does URLSession automatically decode JSON?

No.

URLSession retrieves network data.

You normally use JSONDecoder to convert JSON data into Swift models.

Is URLSession enough for production apps?

Yes, URLSession can serve as the networking foundation of production iOS applications.

Production quality, however, also requires proper architecture around authentication, error handling, retries, caching, logging, decoding, testing, and security.

Recommended Learning Path After URLSession

Once you understand URLSession, continue with:

URLSession Basics
      ↓
HTTP & REST APIs
      ↓
Codable
      ↓
JSONEncoder / JSONDecoder
      ↓
async/await
      ↓
Error Handling
      ↓
Reusable API Client
      ↓
Authentication
      ↓
Pagination
      ↓
File Uploads
      ↓
Caching
      ↓
Dependency Injection
      ↓
Testing
      ↓
Production Networking Architecture

Final Thoughts

URLSession is one of the most important tools to understand when moving from simple SwiftUI projects to real-world iOS applications.

A beginner app may start with:

let (data, response) =
    try await URLSession.shared.data(
        from: url
    )

But production networking eventually involves much more:

SwiftUI
   ↓
State Management
   ↓
ViewModel
   ↓
Repository / Service
   ↓
API Client
   ↓
URLRequest
   ↓
URLSession
   ↓
HTTPS
   ↓
REST API
   ↓
JSON
   ↓
Codable
   ↓
Swift Models

The most important skills are not simply knowing how to send a request.

You should understand:

How HTTP works
How requests are constructed
How responses are validated
How JSON becomes Swift models
How failures are handled
How authentication is secured
How networking is separated from UI
How asynchronous requests affect application state
How the networking layer remains testable and maintainable

Once you understand these concepts, you can build iOS applications that communicate confidently with real APIs and backend services.

That makes URLSession a fundamental skill for becoming a professional Swift and iOS developer.

URLSession in Swift: Complete Guide to Networking and API Integration

What Is URLSession in Swift?

Why Is URLSession Important?

Import Foundation

Understanding HTTP Before URLSession

Common HTTP Methods

Your First URLSession Request

What Is URLSession.shared?

Understanding async and await

What Does throws Mean?

Handling URLSession Errors

Understanding HTTPURLResponse

Understanding HTTP Status Codes

Creating Custom API Errors

Complete Basic GET Request

JSON and URLSession

Creating a Codable Model

Decoding JSON

Complete GET Request with Codable

Decoding an Array

Handling Different JSON Keys

Convert Snake Case Automatically

What Is URLRequest?

Creating a URLRequest

Adding HTTP Headers

Authorization Header

GET Request with Headers

Query Parameters

Why URLComponents Is Better

Making a POST Request

Encode Swift Model to JSON

Complete POST Request

PUT Request

PATCH Request

DELETE Request

Never Decode an Empty Response Blindly

Better APIError Design

Mapping HTTP Status Codes

Handling Decoding Errors

Debugging JSON Responses

Date Decoding

Creating a Reusable API Client

Generic API Client

Using the Generic API Client

Create an Endpoint Type

Avoid Repeating Base URLs

Development vs Production APIs

URLSession Configuration

Request Timeout

Caching

URLSession and Authentication

Never Put API Secrets in an iOS App

Token Refresh

Downloading a File

Downloading an Image as Data

Uploading Data

Multipart Form Data

URLSessionDataTask and Completion Handlers

Completion Handler vs async/await

Cancelling a Network Request

Search Request Cancellation

URLSession in SwiftUI

SwiftUI View Example

Better Loading State

Pagination

Retry Logic

Exponential Backoff

Network Reachability

Handling Offline Mode

URLSession and HTTPS

App Transport Security

HTTP Headers You Should Know

Content-Type vs Accept

URLSession Delegate

Background Downloads

Testing URLSession Code

Protocol-Based Networking

API Service Example

Real-World Networking Architecture

View

What Does `throws` Mean?