(Swift) iOS Apps with REST APIs(

本文及接下来的2篇都是用来讲解如何使用OAuth2.0认证。

重要说明: 这是一个系列教程，非本人原创，而是翻译国外的一个教程。本人也在学习Swift，看到这个教程对开发一个实际的APP非常有帮助，所以翻译共享给大家。原教程非常长，我会陆续翻译并发布，欢迎交流与分享。

如果你是基于REST API来构建一个APP，或许在某些调用的地方需要进行验证。更甚者需要在所有的调用中都需要认证。在使用GitHub API时，我们会给出两种验证方式：基本验证(基于用户名／密码)和OAuth2.0验证。但是对于我们构建的gists APP将只使用OAuth2.0验证。但后面也会讲到使用Mashape进行header/token验证。

GitHub API文档

如果你喜欢深挖文档，那么你可以看一下GitHub API中认证部分。

我们在查看文档的时候可以发现下面几个关键点：

1. GitHub API的验证支持使用基础验证(Basic Auth)和OAuth2.0
2. 如果尝试使用无效的凭据进行认证，将会得到`401 Unauthorized'的错误响应
3. 在没有认证时如果调用需要认证的请求将会返回404 Not Found错误，在某些地方也可能返回403 Forbidden错误

检查你的开发文档中关于认证要求的章节。并实现本章中与你API相匹配的部分。在本章最后还实现了在您的API管理器中的所需要的身份验证集成。

基础认证: 用户名/密码

在Gists App中最终我们将使用OAuth2.0进行认证，但这之前先来看看基础认证是如何工作的。在这里，我们只会在控制台中打印API的结果来确认我们是否成功调用，就像之前的printPublicGists函数一样。不过在后面的章节中我们会实现基于OAuth2.0的认证。

下面让我们先添加一个函数，该函数在基础认证过程中会使用:

class GitHubAPIManager {
    
  // MARK: - Basic Auth
  func printMyStarredGistsWithBasicAuth() -> Void {
    // TODO: 实现它
  }
}

我们还得在路由中增加获取已收藏Gists的调用:

enum GistRouter: URLRequestConvertible {
  static let baseURLString:String = "https://api.github.com"
    
  case GetPublic() // GET https://api.github.com/gists/public 
  case GetMyStarred() // GET https://api.github.com/gists/starred
    
  case GetAtPath(String) // GET at given path
  var URLRequest: NSMutableURLRequest { 
    var method: Alamofire.Method {
      switch self { 
      case .GetPublic:
        return .GET
      case .GetMyStarred:
        return .GET 
      case .GetAtPath:
        return .GET
      }
    }

    let result: (path: String, parameters: [String: AnyObject]?) = { 
      switch self {
      case .GetPublic:
        return ("/gists/public", nil) 
      case .GetMyStarred:
        return ("/gists/starred", nil) 
      case .GetAtPath(let path):
        let URL = NSURL(string: path)
        let relativePath = URL!.relativePath! 
        return (relativePath, nil)
      }
    }()

    let URL = NSURL(string: GistRouter.baseURLString)!
    let URLRequest = NSMutableURLRequest(URL: URL.URLByAppendingPathComponent(result.path))
    let encoding = Alamofire.ParameterEncoding.JSON
    let (encodedRequest, _) = encoding.encode(URLRequest, parameters: result.parameters)
      
    encodedRequest.HTTPMethod = method.rawValue
    return encodedRequest 
  }
}    

首先，让我们像调用公共gists一样来调用(在没有任何认证的情况下)看看会发生什么。修改GitHubAPIController:

func printMyStarredGistsWithBasicAuth() -> Void { 
  Alamofire.request(GistRouter.GetMyStarred()) 
  .responseString { response in
    if let receivedString = response.result.value { 
      print(receivedString)
    }
  }
}

并在MasterViewController修改viewDidAppear测试这个函数:

override func viewDidAppear(animated: Bool) { 
  super.viewDidAppear(animated) 
  loadGists(nil)
  
  // TEST
  GitHubAPIManager.sharedInstance.printMyStarredGistsWithBasicAuth()
  // END TEST
}

保存并运行，控制台中将会打印下面的错误出来:

{
  "message":"Requires authentication",
  "documentation_url":"https://developer.github.com/v3/#authentication"
}

就像文档中所说的，我们需要增加认证信息。最简单的方式就是使用基础认证(Basic Authentication)，通过提供用户名和密码进行认证。基础认证要求在Authorization报头中包含用户名和密码，格式为：username:password，并使用base64进行编码。

Base64编码是一个非常简单的编码方式，它将数据编译成二进制数据，并以文本的方式进行发送。这种类型的编码不提供额外的安全性，因为它仅仅是一个编码，而不是加密。那，为什么基本身份验证时，还要对已经是文本的用户名和密码进行编码呢？其实这个主要的原因是对一些奇怪的字符进行编码，以防止引起HTTP请求问题。

下面让我们先把认证凭据进行Base64编码，让后添加到AuthorizationHTTP请求的报头中。这里你要确认使用了你的正确的GitHub的用户名和密码。然后我们把信息添加到在路由中创建的NSMutableURLRequest中：

let URL = NSURL(string: GistRouter.baseURLString)!
let URLRequest = NSMutableURLRequest(URL: URL.URLByAppendingPathComponent(result.path))
let username = "myUsername" 
let password = "myPassword"

let credentialData = "\(username):\(password)".dataUsingEncoding(NSUTF8StringEncoding)!    
let base64Credentials = credentialData.base64EncodedStringWithOptions([])  

...

第一步我们先构建所要进行编码的字符串:\(username):\(password)。然后使用通用的NSUTF8StringEncoding将它转换NSData。这一步仅仅是将字符串转换为可以进行Base64编码的二进制数据。最后再使用base64EncodedStringWithOptions函数对数据执行Base64编码。

那，该如何发送请求的报头呢？你可以查看前面有关报头章节。

...

URLRequest.setValue("Basic \(base64Credentials)", forHTTPHeaderField: "Authorization") 
let encoding = Alamofire.ParameterEncoding.JSON
let (encodedRequest, _) = encoding.encode(URLRequest, parameters: result.parameters) 

encodedRequest.HTTPMethod = method.rawValue

return encodedRequest 

编译并运行，将得到你所关注Gists的列表(或许运行之前你得先去关注几个Gists)。通过https://gist.github.com/*username*/starred:你将可以得到所关注的Gists列表：

[{"url":"https://api.github.com/gists/3bbe842793ac3f692775","forks_url":"https://api.githu\
b.com/gists/3bbe842793ac3f692775/forks","commits_url":"https://api.github.com/gists/3bbe84\
2793ac3f692775/commits","id":"3bbe842793ac3f692775","git_pull_url":"https://gist.github.co\
m/3bbe842793ac3f692775.git",... 

如果你的API，支持使用Alamofire中的.authenticate函数来发送基础认证的凭据，那么会变得非常简单。可惜GitHub的API不支持，因此我们使用HTTPBIn test API来进行测试。为了测试这个，我们在Alamofire的请求调用中增加.authenticate(user: username, password: password)。该函数将会把认证的需要的信息存放到合适的报头中：

func doGetWithBasicAuth() -> void {
  let username = "myUsername"
  let password = "myPassword"
  Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(username)/\(password)")
    .authenticate(user: username, password: password) 
    .responseString { response in
      if let receivedString = response.result.value { 
        print(receivedString)
      }
  }
}

通常你不需要在请求的URL中添加用户名和密码，这里仅仅是为了使用HTTPBin的测试函数。

另外，你也可以通过NSURLCredential来传递用户名和密码：

func doGetWithBasicAuthCredential() -> void { 
  let username = "myUsername"
  let password = "myPassword"
  
  let credential = NSURLCredential(user: username, password: password, persistence: NSURLCredentialPersistence.ForSession)
  Alamofire.request(.GET, "https://httpbin.org/basic-auth/\(username)/\(password)") 
    .authenticate(usingCredential: credential)
    .responseString { response in
      if let receivedString = response.result.value { 
        print(receivedString)
      }
  }
}

通过NSURLCredentialPersistence可以指定认证凭据的有效期(本次调用、会话期间或者永久)。它也可以和基于证书的认证一起使用。

如果你的API中使用基本的身份验证，那么可以使用凭据以便进行保存。在本章的OAuth章节我们将使用Locksmith把敏感的信息保存到iOS的Keychain中。你也许需要增加一个视图来让用户填写用户名和密码，这个可以参考后面的创建章节，看看如何创建一个简单的表单。或许你还要在APP启动的时候，如果没有检测到用户的认证信息，弹出认证对话框。这些和我们在后面做OAuth2.0认证的时候差不多，所以你可以先去那里查看一下如何开始一个登录流程。

HTTP Header 信息认证

有些API支持使用HTTP Header进行身份认证。在Mashape中你可以找到很多这种API来进行这些测试。比如，Urban Dictionary API。

当你登录了Mashape后，你会得到2个header，并在API调用中进行传递，而不是之前我们使用的基础身份验证:

• X-Mashape-Key:MY_API_KEY
• Accept: application/json

下面的curl语句也是可以执行的：

curl --get --include \
'https://mashape-community-urban-dictionary.p.mashape.com/define?term=hipster' \
-H 'X-Mashape-Key: MY_API_KEY' \
-H 'Accept: application/json'

那么如果使用Alamofire该怎样处理呢？别忘记之前的报头章节，那里有我们需要的所有细节。这些报头在整个会话中都需要，那么我们将来实现它。

一般，如果一个API key需要在所有会话调用中使用，那么我们将为整个会话进行一次性设置，而不是在每次请求中设置。

但，到目前为止，我们都是使用Alamofire.request(...)进行请求。而Alamofire使用一个单一的管理器来处理这些请求，也就是说如果我们像下面这样调用的话是和之前的调用是一样的：

let manager = Alamofire.Manager.sharedInstance
manager.request(...)

这样我们就可以为整个会话设置HTTP报头了，就像我们之前设置GitHub的Accept报头一样。

那下面我们先创建一个管理器，用来和Mashape一起进行工作：

class MashapeAPIManager {
  static let sharedInstance = MashapeAPIManager()
  
  var alamofireManager:Alamofire.Manager 
  
  init () {
    let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
  
    configuration.HTTPAdditionalHeaders = Manager.defaultHTTPHeaders
  
    alamofireManager = Alamofire.Manager(configuration: configuration)
  }
}

添加报头：

init () {
  let configuration = NSURLSessionConfiguration.defaultSessionConfiguration()
  
  var headers = Manager.defaultHTTPHeaders 
  headers["X-Mashape-Key"] = "MY_API_KEY" 
  headers["Accept"] = "application/json" 
  configuration.HTTPAdditionalHeaders = headers
  
  alamofireManager = Alamofire.Manager(configuration: configuration)
}

然后，使用：

let manager = MashapeAPIManager.sharedInstance.alamofireManager 
manager.request(.GET,
"https://mashape-community-urban-dictionary.p.mashape.com/define?term=hipster")

代替之前的：

Alamofire.request(.GET,
"https://mashape-community-urban-dictionary.p.mashape.com/define?term=hipster")

这样X-MASHAPE-KEY:MY_API_KEY将这整个会话期间的每次请求中都会被传递。

如果你的API是使用基础的token/header认证，那么在API管理器中为整个会话进行设置。

如果你现在正在寻找一些API来提高呢的开发技能，可以使用我们的Mashape。这个上面有大把的API，够你折腾的了。

Alamofire验证(Validation)

Alamofire中有一个.validate()的方法，可以在你的请求中这么来使用：

alamofireManager.request(GistRouter.GetMyStarred())
  .validate()
  .responseString { response in
    guard response.result.error == nil else {
      print(response.result.error!)
    }
    if let receivedString = response.result.value {
      print(receivedString)
    }
}

假如你没有在调用中包含对.validate的调用，那么Alamofire将假设调用已成功。在调用返回的类型不是我们所期望的，或返回的状态不在200~299之内时.validate()将返回一个调用失败。旧版本的validate在有错误的时候不会在调用你的自定义序列化方法，并隐藏了一些有价值的错误信息描述。但v3.0.0之后则不会。

下面让我们看看如何在调用GitHub API失败的时候得到更有用的错误信息。

print(response.result.error!)会打印：

Error Domain=com.alamofire.error Code=-1
  "The operation couldn't be completed. (com.alamofire.error error -1.)"

而print(receivedString)将会打印更多有关错误的信息:

{
  "message":"Bad credentials",
  "documentation_url":"https://developer.github.com/v3"
}

因此，在.validate()返回之前最好对JSON进行错误检查：

alamofireManager.request(GistRouter.GetMyStarred()) 
  .validate()
  .responseString { response in
    if let receivedString = response.result.value { 
      print(receivedString)
      let json = SwiftyJSON.JSON(receivedString) 
      // Check for error in JSON
      if let message = json["message"].string {
        let error = Error.errorWithCode(.DataSerializationFailed, failureReason: message) 
        // TODO: bubble up error
      }
      // Do other stuff with JSON
    }
    if error = response.result.error else {
      print(error)
      // TODO: bubble up error
    }
}

现在，使用.validate()将不在隐藏在JSON响应中的错误。

对于一些API或许希望使用JSON来返回比.validate()更详细的错误信息。测试你的API，通过JSON和.validate()打印出错误信息，看看是否应该使用guard语句从返回的错误信息中进行序列化，或者对返回的JSON进行解析并返回。你或许会发现之前返回的"The operation couldn't be completed"错误信息，被"unauthorized"(如：Parse REST API)替代了。这样我们就能够得到一个描述更具体的错误信息，而不是一个通用的网络错误信息。