Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/uploadcare/uploadcare-swift
Swift API client for iOS, iPadOS, tvOS, macOS, and Linux handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.
https://github.com/uploadcare/uploadcare-swift
api client file-upload image-processing image-recognition image-upload ios linux macos processing sdk swift upload uploadcare uploader
Last synced: 26 days ago
JSON representation
Swift API client for iOS, iPadOS, tvOS, macOS, and Linux handles uploads and further operations with files by wrapping Uploadcare Upload and REST APIs.
- Host: GitHub
- URL: https://github.com/uploadcare/uploadcare-swift
- Owner: uploadcare
- License: mit
- Created: 2019-12-20T13:59:22.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-11T06:21:41.000Z (3 months ago)
- Last Synced: 2024-11-10T05:36:14.425Z (about 2 months ago)
- Topics: api, client, file-upload, image-processing, image-recognition, image-upload, ios, linux, macos, processing, sdk, swift, upload, uploadcare, uploader
- Language: Swift
- Homepage: https://uploadcare.com/
- Size: 24.2 MB
- Stars: 12
- Watchers: 4
- Forks: 6
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Swift API client for Uploadcare
[](https://swiftpackageindex.com/uploadcare/uploadcare-swift)
[](https://swiftpackageindex.com/uploadcare/uploadcare-swift)
[](https://github.com/uploadcare/uploadcare-swift/actions/workflows/test.yml)
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](/Demo).
* [Installation](#installation)
* [Initialization](#initialization)
* [Using Upload API](#using-upload-api)
* [Using REST API](#using-rest-api)
* [Demo app](#demo-app)
* [Useful links](#useful-links)
## Installation
### Swift Package Manager
To use a stable version, add a dependency to your `Package.swift` file:
```swift
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:
```swift
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](https://uploadcare.com/dashboard/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-swift) and copy its API keys from there.
Upload API requires only a public key, while REST API requires both public and secret keys:
```swift
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:
```swift
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](https://github.com/uploadcare/uploadcare-swift/blob/master/Documentation/Upload%20API.md) 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:
```swift
guard let url = URL(string: "https://ucarecdn.com/46528d0d-323c-42d7-beab-2fdc5e7077ba/") 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](https://github.com/uploadcare/uploadcare-swift/blob/1e6341edcdcb887589a4e798b746c525c9023b4e/Demo/Demo/Modules/FilesListStore.swift).
## Using REST API
Refer to the [REST API documentation](https://github.com/uploadcare/uploadcare-swift/blob/master/Documentation/REST%20API.md) 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:
```swift
// 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:
```swift
// 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:
```swift
// 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](https://github.com/uploadcare/uploadcare-swift/tree/master/Demo) 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](https://github.com/uploadcare/uploadcare-swift/blob/master/Documentation/Upload%20API.md)
[Swift REST API client documentation](https://github.com/uploadcare/uploadcare-swift/blob/master/Documentation/REST%20API.md)
[Uploadcare documentation](https://uploadcare.com/docs/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-swift)
[Upload API reference](https://uploadcare.com/api-refs/upload-api/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-swift)
[REST API reference](https://uploadcare.com/api-refs/rest-api/v0.7.0/?utm_source=github&utm_medium=referral&utm_campaign=uploadcare-swift)
[Contributing guide](https://github.com/uploadcare/.github/blob/master/CONTRIBUTING.md)
[Security policy](https://github.com/uploadcare/uploadcare-swift/security/policy)
[Support](https://github.com/uploadcare/.github/blob/master/SUPPORT.md)