Swift API client for Uploadcare

Uploadcare Swift API client for iOS, iPadOS, tvOS and macOS handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.

Check out our Demo App.

• Installation
• Initialization
• Using Upload API
• Using REST API
• Demo app
• Useful links

Installation

Swift Package Manager

To use a stable version, add a dependency to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", .branch("master"))
]

If you want to try the current dev version, change the dependency to:

dependencies: [
    .package(url: "https://github.com/uploadcare/uploadcare-swift.git", branch("develop"))
]

To add from Xcode select File -> Swift Packages -> Add Package Dependency and enter the repository URL:

https://github.com/uploadcare/uploadcare-swift

Or you can add it in Xcode to the packages list using that URL: https://github.com/uploadcare/uploadcare-swift (select master branch).

Carthage

To use a stable version, add a dependency to your Cartfile:

github "uploadcare/uploadcare-swift"

To use the current dev version:

github "uploadcare/uploadcare-swift" "develop"

Cocoapods

To use a stable version, add a dependency to your Podfile:

pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift'

To use current dev version:

pod 'Uploadcare', git: 'https://github.com/uploadcare/uploadcare-swift', :branch => 'develop'

Initialization

Create your project in Uploadcare dashboard and copy its API keys from there.

Upload API requires only a public key, while REST API requires both public and secret keys:

final class MyClass {
    private var uploadcare: Uploadcare
    
    init() {
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY")
        
        // Secret key is optional if you want to use Upload API only.
        // REST API requires both public and secret keys:
        self.uploadcare = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY", secretKey: "YOUR_SECRET_KEY")
    }
}

You can create more Uploadcare objects if you need to work with multiple projects in your Uploadcare account:

final class MyClass {
    private let project1: Uploadcare
    private let project2: Uploadcare
    
    init() {
        // A project to use Upload API only 
        self.project1 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_1")

        // A project to use both REST API and Upload API
        self.project2 = Uploadcare(withPublicKey: "YOUR_PUBLIC_KEY_2", secretKey: "YOUR_SECRET_KEY_2")
    }
}

Keep in mind that since Uploadcare is not a singleton. You should store a strong reference (as an instance variable, for example) to your Uploadcare object or it will get deallocated.

Using Upload API

Check the Upload API documentation to see all available methods. Each method has an implementation with a Result completion handler and has an alternative async implementation to use with Swift concurrency.

Example of uploads:

guard let url = URL(string: "https://source.unsplash.com/featured") else { return }
guard let data = try? Data(contentsOf: url) else { return }

// You can create an UploadedFile object to operate with it
var fileForUploading1 = uploadcare.file(fromData: data)
fileForUploading2.metadata = ["myKey": "myValue"]
try await fileForUploading1.upload(withName: "random_file_name.jpg", store: .auto)

// Or you can just upload data and provide a filename

var fileForUploading2 = uploadcare.file(withContentsOf: url)!
let file = try await uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .auto) { progress in
    print("upload progress: \(progress * 100)%")
}

// Same method with a completion callback that returns a task that can be paused or canceled:
let task = uploadcare.uploadFile(data, withName: "random_file_name.jpg", store: .auto, metadata: ["someKey": "someMetaValue"]) { progress in
    print("upload progress: \(progress * 100)%")
} _: { result in
    switch result {
    case .failure(let error):
        print(error.detail)
    case .success(let file):
        print(file)
    }
}
// Cancel uploading if needed
task.cancel()

// task will confirm UploadTaskable protocol if file size is less than 100 mb, and UploadTaskResumable if file size is >= 100mb
// You can pause or resume uploading of file with size >= 100mb if needed
(task as? UploadTaskResumable)?.pause()
(task as? UploadTaskResumable)?.resume()

It is possible to perform uploads in the background. But implementation is platform-specific. This lib doesn't provide a default implementation. You can find an example for the iOS in our Demo app. See FilesListStore.swift.

Using REST API

Refer to the REST API documentation for all methods. Each method has an implementation with a Result completion handler and has an alternative async implementation to use with Swift concurrency.

Example of getting list of files:

// Make a list of files object
lazy var filesList = uploadcare.listOfFiles()

func someFilesListMethod() {
    // Make a query object
    let query = PaginationQuery()
        .stored(true)
        .ordering(.dateTimeUploadedDESC)
        .limit(5)

    // Get file list
    let list = try await filesList.get(withQuery: query)
    
    // Same method with a completion callback.
    filesList.get(withQuery: query) { result in
        switch result {
        case .failure(let error):
            print(error)
        case .success(let list):
            print(list)
        }
    }
}

Get next page:

// Check if the next page is available
guard filesList.next != nil else { return }

// Async:
let next = try await filesList.nextPage()

// With a completion callback:
filesList.nextPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

Get previous page:

// Check if the previous page is available
guard filesList.previous != nil else { return }

// Async:
let previous = try await filesList.previousPage()

// With a completion callback:
filesList.previousPage { result in
    switch result {
    case .failure(let error):
        print(error)
    case .success(let list):
        print(list)
    }
}

Demo app

Check the demo app for usage examples:

• List of files
• List of groups
• File info
• File upload (both direct and multipart, including upload in background)
• Multiple file upload
• Pause and continue multipart uploading
• Project info

Useful links

Swift Upload API client documentation
Swift REST API client documentation
Uploadcare documentation
Upload API reference
REST API reference
Contributing guide
Security policy
Support