Convert Figma logo to code with AI

Moya logoMoya

Network abstraction layer written in Swift.

15,190
1,993
15,190
181

Top Related Projects

41,446

Elegant HTTP Networking in Swift

24,441

Reactive Programming in Swift

Dependency injection framework for Swift with iOS/macOS/Linux

14,957

A simple, decentralized dependency manager for Cocoa

11,317

Model framework for Cocoa and Cocoa Touch

A delightful networking framework for iOS, macOS, watchOS, and tvOS.

Quick Overview

Moya is a network abstraction layer written in Swift that provides a cleaner way to make network requests. It builds on top of Alamofire and combines it with the power of Swift's enums, making network calls more type-safe and easier to manage. Moya aims to simplify network requests by separating the API definition from its implementation.

Pros

  • Type-safe API definitions using Swift enums
  • Easy to mock and test network requests
  • Built-in support for stubbing network responses
  • Simplifies complex authentication and request/response handling

Cons

  • Learning curve for developers new to reactive programming concepts
  • Overhead in setting up for simple API calls
  • Dependency on Alamofire, which may not be desired in all projects
  • Can be overkill for small projects with few API endpoints

Code Examples

  1. Defining an API target:
enum MyService {
    case userProfile(id: Int)
    case updateUser(id: Int, name: String)
}

extension MyService: TargetType {
    var baseURL: URL { URL(string: "https://api.myservice.com")! }
    var path: String {
        switch self {
        case .userProfile(let id):
            return "/users/\(id)"
        case .updateUser(let id, _):
            return "/users/\(id)"
        }
    }
    // Implement other required properties...
}
  1. Making a network request:
let provider = MoyaProvider<MyService>()
provider.request(.userProfile(id: 123)) { result in
    switch result {
    case let .success(response):
        let data = response.data
        // Handle successful response
    case let .failure(error):
        // Handle error
    }
}
  1. Using RxSwift with Moya:
let provider = MoyaProvider<MyService>()
provider.rx.request(.userProfile(id: 123))
    .map(User.self)
    .subscribe(onSuccess: { user in
        print("User: \(user.name)")
    }, onError: { error in
        print("Error: \(error)")
    })
    .disposed(by: disposeBag)

Getting Started

  1. Add Moya to your project using Swift Package Manager:

    dependencies: [
        .package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "15.0.0"))
    ]
    
  2. Import Moya in your Swift file:

    import Moya
    
  3. Define your API target as an enum conforming to TargetType protocol.

  4. Create a provider and make requests:

    let provider = MoyaProvider<MyService>()
    provider.request(.userProfile(id: 123)) { result in
        // Handle the result
    }
    

Competitor Comparisons

41,446

Elegant HTTP Networking in Swift

Pros of Alamofire

  • More flexible and customizable for complex networking scenarios
  • Lighter weight and potentially faster for simple API calls
  • Extensive documentation and large community support

Cons of Alamofire

  • Requires more boilerplate code for basic API requests
  • Less abstraction, which can lead to more repetitive code
  • Steeper learning curve for beginners

Code Comparison

Alamofire example:

AF.request("https://api.example.com/users")
    .responseDecodable(of: [User].self) { response in
        switch response.result {
        case .success(let users):
            print("Users: \(users)")
        case .failure(let error):
            print("Error: \(error)")
        }
    }

Moya example:

provider.request(.getUsers) { result in
    switch result {
    case .success(let response):
        let users = try? response.map([User].self)
        print("Users: \(users ?? [])")
    case .failure(let error):
        print("Error: \(error)")
    }
}

Moya provides a more declarative approach with less boilerplate, while Alamofire offers more granular control over the networking process. Moya is built on top of Alamofire, adding an extra layer of abstraction that can simplify API interactions for many use cases.

24,441

Reactive Programming in Swift

Pros of RxSwift

  • More comprehensive reactive programming framework
  • Supports a wider range of reactive programming concepts and operators
  • Larger community and ecosystem with more extensions and integrations

Cons of RxSwift

  • Steeper learning curve due to its complexity and extensive features
  • Can be overkill for simpler networking tasks
  • Requires more boilerplate code for basic operations

Code Comparison

RxSwift:

Observable.from([1, 2, 3, 4, 5])
    .map { $0 * 2 }
    .filter { $0 > 5 }
    .subscribe(onNext: { print($0) })

Moya:

provider.request(.userProfile) { result in
    switch result {
    case let .success(response):
        let data = response.data
        // Handle the response
    case let .failure(error):
        // Handle the error
    }
}

Summary

RxSwift is a more powerful and flexible reactive programming framework, offering a wide range of operators and concepts. It's ideal for complex reactive programming tasks but may be overwhelming for simpler use cases. Moya, on the other hand, focuses specifically on network abstraction, providing a more straightforward API for handling network requests. While RxSwift requires more setup and learning, it offers greater extensibility and integration with other reactive components. Moya is easier to adopt and use for basic networking tasks but may lack some advanced reactive programming features.

Dependency injection framework for Swift with iOS/macOS/Linux

Pros of Swinject

  • Focused on dependency injection, providing a more comprehensive solution for this specific need
  • Supports object scopes (transient, singleton, etc.) for fine-grained control over object lifecycles
  • Offers circular dependency resolution, which can be useful in complex architectures

Cons of Swinject

  • Steeper learning curve due to its more specialized nature
  • May introduce additional complexity for simpler projects that don't require advanced DI features
  • Less active community compared to Moya (fewer contributors and stars on GitHub)

Code Comparison

Swinject (Dependency Injection):

let container = Container()
container.register(Animal.self) { _ in Cat(name: "Mimi") }
container.register(Person.self) { r in
    PetOwner(pet: r.resolve(Animal.self)!)
}

Moya (Network Abstraction):

let provider = MoyaProvider<MyService>()
provider.request(.userProfile) { result in
    switch result {
    case let .success(response):
        let data = response.data
        // Handle the response
    case let .failure(error):
        // Handle the error
    }
}
14,957

A simple, decentralized dependency manager for Cocoa

Pros of Carthage

  • Decentralized dependency manager, allowing direct use of GitHub repositories
  • Builds frameworks binary, resulting in faster compilation times
  • Supports multiple platforms (iOS, macOS, tvOS, watchOS)

Cons of Carthage

  • Requires manual framework integration into Xcode project
  • Longer initial setup time compared to CocoaPods
  • Limited to Swift and Objective-C projects

Code Comparison

Carthage (Cartfile):

github "Alamofire/Alamofire" ~> 5.0
github "SwiftyJSON/SwiftyJSON" ~> 5.0

Moya (Podfile):

pod 'Moya', '~> 15.0'
pod 'Alamofire', '~> 5.0'

Key Differences

  • Carthage is a dependency manager, while Moya is a network abstraction layer
  • Carthage works with various libraries, Moya focuses on networking
  • Moya integrates with Alamofire, while Carthage can manage Alamofire as a separate dependency
  • Carthage requires manual framework integration, Moya is typically integrated via CocoaPods or Swift Package Manager

Use Cases

  • Choose Carthage for projects requiring fine-grained control over dependencies across multiple platforms
  • Opt for Moya when building iOS apps with a focus on clean, easy-to-use networking layer abstraction
11,317

Model framework for Cocoa and Cocoa Touch

Pros of Mantle

  • Focuses on model layer and data parsing, providing a robust solution for object serialization and deserialization
  • Offers powerful key-value coding and key-value observing capabilities
  • Has a longer history and more mature codebase, with extensive documentation and community support

Cons of Mantle

  • Limited to model layer functionality, not providing network abstraction like Moya
  • May require more setup and configuration for complex data structures
  • Less actively maintained in recent years compared to Moya

Code Comparison

Mantle (model definition):

@interface MTLUser : MTLModel <MTLJSONSerializing>
@property (nonatomic, copy, readonly) NSString *name;
@property (nonatomic, assign, readonly) NSUInteger age;
@end

Moya (network request definition):

enum UserService {
    case createUser(name: String, age: Int)
    case getUser(id: Int)
}

extension UserService: TargetType {
    // Implementation details
}

While Mantle focuses on model layer operations, Moya provides a higher-level abstraction for network requests. Mantle is better suited for projects requiring complex object mapping and data transformation, while Moya excels in simplifying API interactions and network layer management.

A delightful networking framework for iOS, macOS, watchOS, and tvOS.

Pros of AFNetworking

  • More mature and battle-tested, with a longer history of use in production environments
  • Offers lower-level control over network requests and responses
  • Provides a wider range of networking features beyond just HTTP requests

Cons of AFNetworking

  • Requires more boilerplate code for common tasks
  • Less opinionated, which can lead to inconsistent usage across projects
  • Steeper learning curve for beginners due to its extensive API

Code Comparison

AFNetworking:

let manager = AFHTTPSessionManager()
manager.get("https://api.example.com/data", parameters: nil, progress: nil, success: { (task, responseObject) in
    print("Success: \(responseObject)")
}) { (task, error) in
    print("Error: \(error.localizedDescription)")
}

Moya:

provider.request(.getData) { result in
    switch result {
    case let .success(response):
        print("Success: \(response.data)")
    case let .failure(error):
        print("Error: \(error.localizedDescription)")
    }
}

AFNetworking offers more granular control but requires more setup, while Moya provides a more streamlined and declarative approach to networking tasks.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Moya 15.0.0

CircleCI codecov.io Carthage compatible Accio supported CocoaPods compatible Swift Package Manager compatible

A Chinese version of this document can be found here.

You're a smart developer. You probably use Alamofire to abstract away access to URLSession and all those nasty details you don't really care about. But then, like lots of smart developers, you write ad hoc network abstraction layers. They are probably called "APIManager" or "NetworkModel", and they always end in tears.

Moya Overview

Ad hoc network layers are common in iOS apps. They're bad for a few reasons:

  • Makes it hard to write new apps ("where do I begin?")
  • Makes it hard to maintain existing apps ("oh my god, this mess...")
  • Makes it hard to write unit tests ("how do I do this again?")

So the basic idea of Moya is that we want some network abstraction layer that sufficiently encapsulates actually calling Alamofire directly. It should be simple enough that common things are easy, but comprehensive enough that complicated things are also easy.

If you use Alamofire to abstract away URLSession, why not use something to abstract away the nitty gritty of URLs, parameters, etc?

Some awesome features of Moya:

  • Compile-time checking for correct API endpoint accesses.
  • Lets you define a clear usage of different endpoints with associated enum values.
  • Treats test stubs as first-class citizens so unit testing is super-easy.

You can check out more about the project direction in the vision document.

Sample Projects

We have provided two sample projects in the repository. To use it download the repo, run carthage update to download the required libraries and open Moya.xcodeproj. You'll see two schemes: Basic and Multi-Target - select one and then build & run! Source files for these are in the Examples directory in project navigator. Have fun!

Project Status

This project is actively under development, and is being used in Artsy's auction app. We consider it ready for production use.

Installation

Moya version vs Swift version.

Below is a table that shows which version of Moya you should use for your Swift version.

SwiftMoyaRxMoyaReactiveMoyaRxSwiftReactiveSwiftAlamofire
>= 5.2>= 15.0.0>= 15.0.0>= 15.0.06.X6.X5.X
5.X>= 14.0.0>= 14.0.0>= 14.0.05.X6.X5.X
5.X>= 13.0.0>= 13.0.0>= 13.0.04.X5.X>= 4.1
4.X9.0.0 - 12.0.110.0.0 - 12.0.19.0.0 - 12.0.14.X(>= 10.0.0)4.X(>= 12.0.0)4.1(>= 11.0.0)
3.X8.0.0 - 8.0.58.0.0 - 8.0.58.0.0 - 8.0.5---
2.37.0.2 - 7.0.47.0.2 - 7.0.47.0.2 - 7.0.4---
2.2<= 7.0.1<= 7.0.1<= 7.0.1---

Note: If you are using Swift 4.2 in your project, but you are using Xcode 10.2, Moya 13 should work correctly even though we use Swift 5.0.

Upgrading to a new major version of Moya? Check out our migration guides.

Swift Package Manager

Note: Instructions below are for using SwiftPM without the Xcode UI. It's the easiest to go to your Project Settings -> Swift Packages and add Moya from there.

To integrate using Apple's Swift package manager, without Xcode integration, add the following as a dependency to your Package.swift:

.package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "15.0.0"))

and then specify "Moya" as a dependency of the Target in which you wish to use Moya. If you want to use reactive extensions, add also "ReactiveMoya", "RxMoya" or "CombineMoya" as your target dependency respectively. Here's an example PackageDescription:

// swift-tools-version:5.3
import PackageDescription

let package = Package(
    name: "MyPackage",
    products: [
        .library(
            name: "MyPackage",
            targets: ["MyPackage"]),
    ],
    dependencies: [
        .package(url: "https://github.com/Moya/Moya.git", .upToNextMajor(from: "15.0.0"))
    ],
    targets: [
        .target(
            name: "MyPackage",
            dependencies: ["ReactiveMoya"])
    ]
)

Combine note: if you're using CombineMoya, make sure that you use Xcode 11.5.0 or later. With earlier versions of Xcode you will have to manually add Combine as a weakly linked framework to your application target.

Accio

Accio is a dependency manager based on SwiftPM which can build frameworks for iOS/macOS/tvOS/watchOS. Therefore the integration steps of Moya are exactly the same as described above. Once your Package.swift file is configured, run accio update instead of swift package update.

CocoaPods

For Moya, use the following entry in your Podfile:

pod 'Moya', '~> 15.0'

# or 

pod 'Moya/RxSwift', '~> 15.0'

# or

pod 'Moya/ReactiveSwift', '~> 15.0'

# or

pod 'Moya/Combine', '~> 15.0'

Then run pod install.

In any file you'd like to use Moya in, don't forget to import the framework with import Moya.

Carthage

Carthage users can point to this repository and use whichever generated framework they'd like, Moya, RxMoya, ReactiveMoya, or CombineMoya.

Make the following entry in your Cartfile:

github "Moya/Moya" ~> 15.0

Then run carthage update --use-xcframeworks.

If this is your first time using Carthage in the project, you'll need to go through some additional steps as explained over at Carthage.

NOTE: At this time, Carthage does not provide a way to build only specific repository submodules. All submodules and their dependencies will be built with the above command. However, you don't need to copy frameworks you aren't using into your project. For instance, if you aren't using ReactiveSwift, feel free to delete that framework along with ReactiveMoya from the Carthage Build directory after carthage update completes. Or if you are using ReactiveSwift but not RxSwift or Combine, then RxMoya, RxTest, RxCocoa, CombineMoya etc. can safely be deleted.

Manually

  • Open up Terminal, cd into your top-level project directory, and run the following command if your project is not initialized as a git repository:
$ git init
  • Add Alamofire & Moya as a git submodule by running the following commands:
$ git submodule add https://github.com/Alamofire/Alamofire.git
$ git submodule add https://github.com/Moya/Moya.git
  • Open the new Alamofire folder, and drag the Alamofire.xcodeproj into the Project Navigator of your application's Xcode project. Do the same with the Moya.xcodeproj in the Moya folder.

They should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.

  • Verify that the deployment targets of the xcodeprojs match that of your application target in the Project Navigator.
  • Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
  • In the tab bar at the top of that window, open the "General" panel.
  • Click on the + button under the "Embedded Binaries" section.
  • You will see two different Alamofire.xcodeproj folders each with two different versions of the Alamofire.framework nested inside a Products folder.

It does not matter which Products folder you choose from, but it does matter whether you choose the top or bottom Alamofire.framework.

  • Select the top Alamofire.framework for iOS and the bottom one for macOS.

You can verify which one you selected by inspecting the build log for your project. The build target for Alamofire will be listed as either Alamofire iOS, Alamofire macOS, Alamofire tvOS or Alamofire watchOS.

  • Click on the + button under "Embedded Binaries" again and add the correct build target for Moya.

  • And that's it!

The three frameworks are automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.

Usage

After some setup, using Moya is really simple. You can access an API like this:

provider = MoyaProvider<GitHub>()
provider.request(.zen) { result in
    switch result {
    case let .success(moyaResponse):
        let data = moyaResponse.data
        let statusCode = moyaResponse.statusCode
        // do something with the response data or statusCode
    case let .failure(error):
        // this means there was a network failure - either the request
        // wasn't sent (connectivity), or no response was received (server
        // timed out).  If the server responds with a 4xx or 5xx error, that
        // will be sent as a ".success"-ful response.
    }
}

That's a basic example. Many API requests need parameters. Moya encodes these into the enum you use to access the endpoint, like this:

provider = MoyaProvider<GitHub>()
provider.request(.userProfile("ashfurrow")) { result in
    // do something with the result
}

No more typos in URLs. No more missing parameter values. No more messing with parameter encoding.

For more examples, see the documentation.

Reactive Extensions

Even cooler are the reactive extensions. Moya provides reactive extensions for ReactiveSwift, RxSwift, and Combine.

ReactiveSwift

ReactiveSwift extension provides both reactive.request(:callbackQueue:) and reactive.requestWithProgress(:callbackQueue:) methods that immediately return SignalProducers that you can start, bind, map, or whatever you want to do. To handle errors, for instance, we could do the following:

provider = MoyaProvider<GitHub>()
provider.reactive.request(.userProfile("ashfurrow")).start { event in
    switch event {
    case let .value(response):
        image = UIImage(data: response.data)
    case let .failed(error):
        print(error)
    default:
        break
    }
}

RxSwift

RxSwift extension also provide both rx.request(:callbackQueue:) and rx.requestWithProgress(:callbackQueue:) methods, but return type is different for both. In case of a normal rx.request(:callbackQueue), the return type is Single<Response> which emits either single element or an error. In case of a rx.requestWithProgress(:callbackQueue:), the return type is Observable<ProgressResponse>, since we may get multiple events from progress and one last event which is a response.

To handle errors, for instance, we could do the following:

provider = MoyaProvider<GitHub>()
provider.rx.request(.userProfile("ashfurrow")).subscribe { event in
    switch event {
    case let .success(response):
        image = UIImage(data: response.data)
    case let .error(error):
        print(error)
    }
}

In addition to the option of using signals instead of callback blocks, there are also a series of signal operators for RxSwift and ReactiveSwift that will attempt to map the data received from the network response into either an image, some JSON, or a string, with mapImage(), mapJSON(), and mapString(), respectively. If the mapping is unsuccessful, you'll get an error on the signal. You also get handy methods for filtering out certain status codes. This means that you can place your code for handling API errors like 400's in the same places as code for handling invalid responses.

Combine

Combine extension provides requestPublisher(:callbackQueue:) and requestWithProgressPublisher(:callbackQueue) returning AnyPublisher<Response, MoyaError> and AnyPublisher<ProgressResponse, MoyaError> respectively.

Here's an example of requestPublisher usage:

provider = MoyaProvider<GitHub>()
let cancellable = provider.requestPublisher(.userProfile("ashfurrow"))
    .sink(receiveCompletion: { completion in
        guard case let .failure(error) = completion else { return }

        print(error)
    }, receiveValue: { response in
        image = UIImage(data: response.data)
    })

Community Projects

Moya has a great community around it and some people have created some very helpful extensions.

Contributing

Hey! Do you like Moya? Awesome! We could actually really use your help!

Open source isn't just writing code. Moya could use your help with any of the following:

  • Finding (and reporting!) bugs.
  • New feature suggestions.
  • Answering questions on issues.
  • Documentation improvements.
  • Reviewing pull requests.
  • Helping to manage issue priorities.
  • Fixing bugs/new features.

If any of that sounds cool to you, send a pull request! After your first contribution, we will add you as a member to the repo so you can merge pull requests and help steer the ship :ship: You can read more details about that in our contributor guidelines.

Moya's community has a tremendous positive energy, and the maintainers are committed to keeping things awesome. Like in the CocoaPods community, always assume positive intent. Even if a comment sounds mean-spirited, give the person the benefit of the doubt.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Adding new source files

If you add or remove a source file from Moya, a corresponding change needs to be made to the Moya.xcodeproj project at the root of this repository. This project is used for Carthage. Don't worry, you'll get an automated warning when submitting a pull request if you forget.

Help us improve Moya documentation

Whether you’re a core member or a user trying it out for the first time, you can make a valuable contribution to Moya by improving the documentation. Help us by:

  • Sending us feedback about something you thought was confusing or simply missing.
  • Suggesting better wording or ways of explaining certain topics.
  • Sending us a pull request via GitHub.
  • Improving the Chinese documentation.

License

Moya is released under an MIT license. See License.md for more information.