AmazonS3RequestManager

An Alamofire based request manager that serializes requests to the AWS S3 (Amazon Simple Storage Solution).

AmazonS3RequestManager also includes a request serializer that creates URLRequest objects for use with any other networking methods.

Features

• Request Serialization
• Response Validation
• Amazon S3 Response Error Parsing
• Access Control List (ACL) Management
• Support for Amazon S3 Subresources
• Support for Amazon S3 Storage Classes
• Comprehensive Unit Test Coverage
• Complete Documentation

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects.

To integrate AmazonS3RequestManager into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

// For Swift 2.0
pod 'AmazonS3RequestManager', '~> 0.10'

Then, run the following command:

$ pod install

Usage

First create an instance of the manager.

let amazonS3Manager = AmazonS3RequestManager(bucket: myAmazonS3Bucket,
    region: .USStandard,
    accessKey: myAmazonS3AccessKey,
    secret: myAmazonS3Secret)

List Bucket Objects

Gets a list of object in a bucket:

amazonS3Manager.listBucketObjects().responseS3Object { (response: DataResponse<S3BucketObjectList, NSError>) in
    if let files = response.result.value?.files {
        for file in files {
            print(file.path)
        }
    }
}

Get Objects

Getting Objects as Response Objects:

amazonS3Manager.get(at: "myFolder/fileName.jpg")

Saving Objects To File:

let destinationURL: URL = FileManager.defaultManager().URLsForDirectory(.DocumentDirectory, inDomains: .UserDomainMask)[0]
let destination: DownloadRequest.DownloadFileDestination = { _, _ in destinationURL, []) }
amazonS3Manager.download(at: "myFolder/fileName.jpg", to: destination)

Get Metadata

Retrieve metadata from an object without returning the object itself:

amazonS3Manager.getMetaData(forObjectAt: "fileName.txt").responseS3MetaData { (response: DataResponse<S3ObjectMetaData, NSError>) in
    if let metaData = response.result.value?.metaData {
        for objectMetaData in metaData {
            print(objectMetaData)
        }
    }
}

Upload Objects

let fileURL: NSURL = NSURL(fileURLWithPath: "pathToMyObject")
amazonS3Manager.upload(from: fileURL, to: "pathToSaveObjectTo/fileName.jpg")

Copy Objects

amazonS3Manager.copy(from: "demo.txt", to: "copy.txt").response { request, response, data, error in    
    print(response)    
    print(error)
}

Delete Objects

amazonS3Manager.delete(at: "myFolder/fileName.jpg")

Response Serialization

AmazonS3RequestManager includes a custom data response serializer that parses errors from the Amazon S3 Service.

amazonS3Manager.getObject("myFolder/fileName.jpg")
  .responseS3Data { (response) -> Void in
    // Handle Response Data or Error
}

Access Control Lists (ACL)

AmazonS3RequestManager provides simple APIs for getting and setting ACLs on buckets and objects.

Getting ACLs

You can retrieve the ACLs for the current bucket set on the request manager with a GET request:

amazonS3Manager.getBucketACL()

or for an object in the bucket with a GET request:

amazonS3Manager.getACL(forObjectAt: "myFolder/fileName.jpg")

Setting ACLs

You can set the ACLs on the current bucket with a PUT request:

amazonS3Manager.setBucketACL(AmazonS3PredefinedACL.Public)

or on an object in the bucket with a PUT request:

amazonS3Manager.setACL(acl: PredefinedACL.publicReadWrite, forObjectAt: "myFolder/fileName.jpg")

The ACLs for an object can also be set while uploading by using the optional acl parameter.

Creating Custom ACLs

If the predefined ACLs that the Amazon S3 Service provides do not give you enough control, you may create custom ACLs using AmazonS3ACLPermissionGrant and AmazonS3CustomACL

AmazonS3ACLPermissionGrant grants multiple users/user groups a single permission. AmazonS3CustomACL is comprised of multiple AmazonS3ACLPermissionGrants to create any series of permissions you would like to create.

Examples

To give all users read access to the bucket:

let readPermission = AmazonS3ACLPermissionGrant(permission: .Read, grantee: .AllUsers)
amazonS3Manager.setBucketACL(readPermission)

To give all users read access to the bucket, authenticated users write access to the bucket, and two users with a given E-mail Address and given User ID full control:

let readPermission = AmazonS3ACLPermissionGrant(permission: .Read, grantee: .AllUsers)
let writePermission = AmazonS3ACLPermissionGrant(permission: .Write, grantee: .AuthenticatedUsers)
let fullControlPermission = AmazonS3ACLPermissionGrant(permission: .FullControl, grantees: [.EmailAddress("admin@myDomain.com"), .UserID("my-user-id")])
let customACL = AmazonS3CustomACL(grants: [readPermission, writePermission, fullControlPermission])
amazonS3Manager.setBucketACL(customACL)

1.0.0 Migration

Version 1.0.0 changes the names public classes and functions to adopt the recommended syntax from the Swift API Design Guidelines. The language version has also been updated to use Swift 3.0.

• Removes AmazonS3 prefix from some objects, classes, and enums.
• ACL protocol method parameter name changed from setACLHeaders(forRequest:) to 'setACLHeaders(on:)`.
• PredefinedACL case name changes
  • Private -> privateReadWrite
  • Public -> publicReadWrite
• Changed request method names on AmazonS3RequestManager.
  • getObject(path:) -> get(at:)
  • downloadObject(path:saveToURL:) -> download(at:to:)
  • putObject(fileURL:destinationPath:acl:metaData:storageClass:) -> upload(from:to:acl:metaData:storageClass:)
  • putObject(data:destinationPath:acl:metaData:storageClass:) -> upload(_:to:acl:metaData:storageClass:)
  • headObject(path:) -> getMetaData(forObjectAt:)
  • copyObject(_:destinationPath:) -> copy(from:to:)
  • deleteObject(_:) -> delete(at:)
  • getACL(forObjectAtPath:) -> getACL(forObjectAt:)
  • setACL(forObjectAtPath:acl:) -> setACL(_:forObjectAt:)
• Alamofire now uses a DownloadFileDestination to configure the destination for download requests. You will need to migrate all download requests to use this time, rather than just the destination URL.