How to implement universal networking module in Swift (pt.1)

What’s the first service you usually implement in an app?

It’s either networking or storage, right? And when it comes to networking, what are your choices? Most people either operate on URLSession directly, leveraging its multiple APIs, or add a 3rd party library like Alamofire

But there is also a third option: implementing your own networking client. 

When I was starting a new project a couple of years ago, I decided to give it a try. Since then, I have managed  to reuse the core concepts of that network client in many applications, trying to perfect their design in each iteration. 

Recently, with the great help from my friend Kemal, the Networking Client has been made open-source:, and a recommended option to implement the networking in new iOS apps developed at Netguru.

Improvise, adopt, overcome - Implementing universal networking module

You might ask: why should I even bother? Alamofire would definitely allow me to execute every kind of url request and parse every possible response without an issue.
And you’ll be correct. Alamofire is a great library. However, it’s also worth asking why nearly all of the top projects rely on custom, home-made networking components. When you think of it, the answer is simple. The team has to be in control of all the project dependencies, especially when these dependencies are many and complex. 

Have you ever considered writing your own networking client? Or if you already use one, making it open-source? If so, I hope this 2-part guide will be of some help. 

In this post, we’ll take a look at how to create a networking module, define its basic components and their purposes. That should be enough to get you started. 

In the second part, we’ll explore e.g. extending the module functionalities, exposing additional APIs, and making it open-source.

Without further ado, let’s roll!

Where to start?

Unless you have a strong reason not to, it’s highly recommended to use Swift Package Manager to package your networking client. SPM is built into Xcode and can be used alongside other dependency providers like Cocoapods.

The first order of business will be to create a package and name basic targets:

let package = Package(
    products: [
            name: "NgNetworkModule",
            targets: ["NgNetworkModule"]
    dependencies: [],
    targets: [
            name: "NgNetworkModule",
            dependencies: []
            name: "NgNetworkModuleTests",
            dependencies: ["NgNetworkModule"]

What’s worth noticing, there are no external dependencies. And that’s a good thing. Whenever possible, we should avoid 3rd party dependencies. Foundation framework will provide us all the tools we’d ever need 😉

Before we get to coding however, let’s write down the components a typical networking client should consist of:

  • A request builder – a component responsible for composing a URLRequest from an abstraction describing it (containing e.g. request method, url, etc.)
  • A network session – to execute requests on
  • A network response parser – to determine if a request succeeded and decode received data
  • A network error – to describe different HTTP errors in more readable and structured way
  • A single point of entry into the networking client, providing user-facing APIs

In addition, we should also think of a way to allow users to extend the networking client functionality. We will come back to this topic in the 2nd part of this post, so stay tuned! 

Composing URL Requests

Let’s start by defining an abstraction describing a network request:

protocol NetworkRequest {
    var path: String { get }
    var method: NetworkRequestType { get }
    var additionalHeaderFields: [String: String] { get }
    var parameters: [String: String]? { get }
    var body: Encodable? { get }

It looks great but didn’t you forget something? How will this protocol be consumed? Will it only be accessed internally or outside of the module as well


public protocol NetworkRequest {  }

Much better now. Don’t beat yourself up if you forget about the public keyword before the APIs you wish to expose. Aside from internal and private, we rarely use other access modifiers ;).

It’s also worth making lives of the users easier by preparing default implementations for all the optional request fields:

public extension NetworkRequest {

    var parameters: [String: String]? {

    var body: Encodable? {



Ok, we have an abstraction describing a request – let’s define an object to turn that abstraction into a “usable” request:

public protocol RequestBuilder: AnyObject {

    func build(request: NetworkRequest) -> URLRequest?

And some implementation details:

public final class DefaultRequestBuilder: RequestBuilder {
    private let baseURL: URL

    public init(baseURL: URL) {
        self.baseURL = baseURL

    public func build(request: NetworkRequest) -> URLRequest? {
        guard let url = composeURL(request: request) else {
            return nil

        var urlRequest = URLRequest(url: url)
        urlRequest.httpMethod = request.method.value
        urlRequest.httpBody = request.encodedBody
        append(additionalHeaderFields: request.additionalHeaderFields, toRequest: &urlRequest)

        return urlRequest

As you can see, we created a neat object that turns a description of the network request into a URLRequest we can send via URLSession. A picture-perfect example of the Single Responsibility Principle in action. And as we all know, having “responsibles” is very important part of life:

Describing errors

Naturally, things can go wrong. E.g. a base URL path might be nil, request parameters invalid, etc. In such a case, a URLRequest will simply fail to build, and the user should be notified immediately. To do that, let’s introduce another part of the module: a network error description:

public enum NetworkError: Error, Equatable {

    /// Network errors associated with sending a request:
    case notFound
    case forbidden
    case unauthorized
    case invalidRequest(code: Int, message: String?)
    case serverError(code: Int, message: String?)
    case custom(code: Int, message: String?)
    case cancelled

    /// Network errors associated with parting a response:
    case requestParsingFailed
    case responseParsingFailed
    case noResponseData

    /// Other errors:
    case unknown

But wait… Standard errors returned by the URLSession do not look like this… How can I translate a generic Error to the enum cases you described? The answer is simple. Let’s make an initializer accepting: the error code and localized message:

public enum NetworkError: Error, Equatable {

    public init?(code: Int, message: String?) {
        switch code {
        case 200...399:
            return nil
        case 404:
            self = .notFound
        case 403:
            self = .forbidden
        case 401:
            self = .unauthorized
        case 400...499:
            self = .invalidRequest(code: code, message: message)
        case 500...599:
            self = .serverError(code: code, message: message)


            self = .custom(code: code, message: message)

Additionally, you may consider creating convenience initializers utilizing other basic networking types: NSError, HTTPURLResponse, etc.:

public init(error: NSError) {
    self = NetworkError(code: error.code, message: error.localizedDescription) ?? .unknown

As a result, we now have a way to describe almost all the issues that might arise while using our networking client:

  • Before sending a request – e.g. requestParsingFailed
  • After receiving an answer – e.g. notFound, unauthorised or forbidden errors.
  • When we tried to parse the data received from the backend – e.g. responseParsingFailed or noResponseData errors.
  • And the unknown error to cover other issues

Putting it all together

Cool! We have means to build a request and describe errors. Now, let’s define the heart of the networking client:

public protocol NetworkModule: AnyObject {

    @discardableResult func perform(
        request: NetworkRequest,
        completion: ((Result<NetworkResponse, NetworkError>) -> Void)?
    ) -> URLSessionTask?

    @discardableResult func perform(
        urlRequest: URLRequest,
        completion: ((Result<NetworkResponse, NetworkError>) -> Void)?
    ) -> URLSessionTask

According to a well-known rule, a good API should be tolerant of input and precise about output. TLDR: we should accept a variety of input data, but be very strict on what we return to the user. In this case, we accept either a URLRequest, or NetworkRequest, returning a well-proven Result object in a callback. It will contain either a network response (wrapped in an abstraction for improved readability), or a NetworkError.

Naturally, if you provide the expected response data type, the NetworkModule can automatically decode it for you:

public extension NetworkModule {

    @discardableResult func performAndDecode<T: Decodable>(
        request: NetworkRequest,
        responseType: T.Type,
        decoder: JSONDecoder = JSONDecoder(),
        completion: ((Result<T, NetworkError>) -> Void)?
    ) -> URLSessionTask? {
        perform(request: request) { result in
            switch result {
            case let .success(response):
                completion?(response.decoded(into: responseType, decoder: decoder))
            case let .failure(error):

    @discardableResult func performAndDecode<T: Decodable>(
        urlRequest: URLRequest,
        responseType: T.Type,
        decoder: JSONDecoder = JSONDecoder(),
        completion: ((Result<T, NetworkError>) -> Void)?
    ) -> URLSessionTask {
        perform(urlRequest: urlRequest) { result in
            switch result {
            case let .success(response):
                completion?(response.decoded(into: responseType, decoder: decoder))
            case let .failure(error):

As you can see, we’re just reusing the methods we already defined in the NetworkModule protocol. On top of that, we stay true to being tolerant of the API input, allowing users to choose their preferred request type and provide their own decoder for the response.

Finally let’s take a look at the NetworkModule implementation:

public init(
     requestBuilder: RequestBuilder,
     urlSession: NetworkSession = URLSession.shared,
     actions: [NetworkModuleAction] = [],
     completionExecutor: AsynchronousOperationsExecutor = MainQueueOperationsExecutor()
 ) {
     self.requestBuilder = requestBuilder
     self.urlSession = urlSession
     self.actions = actions
     self.completionExecutor = completionExecutor

As you can see, the only component we have to provide is the Request Builder. However, if we want to execute requests on a specific URLSession, or receive a response on a background queue, you can do so. All it takes is passing a proper object in the Network Module constructor. We relied heavily on these features to execute the Unit Tests suite without making actual network calls ;). 

The Network Module Actions and their importance will be described in detail in part 2 of this post.

Ok, let’s see how a request is executed. First, we need to build an URLRequest from a provided description. If we can’t, there’s nothing to execute 😉

@discardableResult public func perform(request: NetworkRequest, completion: … ) -> URLSessionTask? {
    guard let urlRequest = request) else {
        execute(completionCallback: completion, result: .failure(.requestParsingFailed))
        return nil

    return perform(urlRequest: urlRequest, withOptionalContext: request, completion: completion)

When this is done, we can start a URLSession data task and wait for a response. Once it arrives, we try to figure out its status. Ultimately, unless the request has been canceled, we should notify the caller of the request result:

@discardableResult func perform(urlRequest: URLRequest, … ) -> URLSessionTask {
    var urlRequest = urlRequest


    let task = urlSession.dataTask(with: urlRequest) { [weak self] data, response, error in
        if let error = error as NSError? {
            self?.handle(error: error, completion: completion)
        } else if let response = response as? HTTPURLResponse {
            self?.handle(response: response, data: data, request: networkRequest, completion: completion)
        } else {
            self?.execute(completionCallback: completion, result: .failure(NetworkError.unknown))

    return task


func handle(response: HTTPURLResponse, data: Data?, ...) {
    if let networkError = response.toNetworkError() {
        execute(completionCallback: completion, result: .failure(networkError))

    let networkResponse = NetworkResponse(data: data, networkResponse: response)
    execute(completionCallback: completion, result: .success(networkResponse))

func handle(error: NSError, …) {
    let networkError = NetworkError(error: error)
    guard networkError != .cancelled else {

    execute(completionCallback: completion, result: .failure(networkError))

And that’s really it? Yes! Networking on iOS can get complicated only if you allow it!

The story so far

To wrap up, let’s take a look at a networking client creation to-do list:

  • Setting up SPM module and defining its targets
  • Implementing URLRequest composition
  • Describing and handling various network errors
  • Creating a single point of entry for the user – the NetworkModule.

As you were able to see, all the basic components are responsible for specific tasks (e.g. composing a URL Request), clear, readable and fully testable. The networking client offers a variety of ways to execute network requests and process the response. Finally, there’s almost no code duplication – all the functionalities added in extensions rely on the primary Network Module APIs.

Surely, that can’t be all, can it? You must have many questions:

  • Why did we use this awful, callback-based API
  • How can users extend the NetworkModule and modify its default behavior?
  • Are there any formal requirements a library has to meet before being open-sourced?

Unfortunately, this post is far too long already without even starting to address these topics 😉
If you’d like to know, hop right into part 2!

Don’t miss any new blogposts!

    By subscribing, you agree with our privacy policy and our terms and conditions.

    Disclaimer: All memes used in the post were made for fun and educational purposes only 😎
    They were not meant to offend anyone 🙌
    All copyrights belong to their respective owners🧐
    The thumbnail was generated with text2image ❤️