iOS Apps with REST APIs(一)

重要说明: 这是一个系列教程，非本人原创，而是翻译国外的一个教程。本人也在学习Swift，看到这个教程对开发一个实际的APP非常有帮助，所以翻译共享给大家。原教程非常长，我会陆续翻译并发布，欢迎交流与分享。
另，原教程有第一章，讲述该教程及相关基础概念，感觉没有什么必要翻译，所以这里略过。有兴趣的可以自行上网去找原版教程。

再另，原文发布在我的博客中：iOS Apps with REST APIs(一)

App需求

直接去编码对我们这些码农来说总是很有诱惑力的，但是如果我们事先先搞清楚要做什么，并做好计划，是不是可以让编码更顺利。或者至少我们得对需要编写的应用(App)有一些想法吧。Ok，下面让我们列出gist s这个应用(App)的需求，你可以根据你所要构建的应用进行修改。

首先我们来列出来应用中有那些界面。当然我们有很多种方式可以完成这事，不过我喜欢先列出用户希望通过这款应用要完成那些事情，然后再进行界面设计就容易多了。

那么我们的用户会使用gists做什么呢？Gists是一些代码的片段，通过GitHub可以分享给其他用户。因此用户通过gists可能需要以下功能：

1. 查看公共的gists库列表，看看有哪些新鲜的东东；
2. 查询感兴趣的gists库，通常是通过编程语言进行查询；
3. 收藏/关注一个gists库，后面可以查看；
4. 查看自己所收藏/关注的gists库列表；
5. 查看自己的gists库，保存一些常用的代码，以后不用每次都要再敲一遍；
6. 查看公共、自己或者收藏的gists库的详情；
7. 创建新的gists库；
8. 删除自己的gists库。

列出你的应用中的任务或者用户故事。与gistsApp做一个对比，对比时重点关注一下不同的对象(如：收藏、用户，及gists库)以及动作(如：查看列表、查看一个对象的详情、增加、删除等)。

或许你列表很长，那么这时候你需要考虑一下是否都需要在第一版中实现，如果不是，可以将哪些功能分离到下一个版本中实现。

现在评估你的列表中的每一项功能，判断哪些是需要在第一版中实现。现在说不定你已经开始想设计第二版了。但是，一个可以运行的应用要远比一个无限期延迟发布的完美应用要好。

匹配功能与API端点(endpoint)

接下来，我们为功能列表中的每一项，找出如何使用API接口获取需要显示的数据。我们会检查Github GISTs API文档，然后为每个功能找到相应的API端点(endpoint)。我们也会标出哪些API端点需要进行特殊处理的，比如身份验证或分页。

公共gists库列表

  GET /gists/public

不需要身份验证。如果我们查看20条以后的，那么需要使用分页来加载更多数据。

查询Gists库

Github没有为此提供接口。我们的应用如果没有查询功能还是非常不错的，所以就先不做这个功能。

收藏/取消收藏Gists库

  PUT /gists/:id/star
  DELETE /gists/:id/star

需要身份验证。

收藏列表

  GET /gists/starred

需要身份验证。

我的Gists列表

有两种方式获取一个用户的gists列表：

  GET /users/:username/gists

如果已经验证，可以使用：

  GET /gists

查看Gist详情

我们可以通过列表视图传递gists的详情数据给详情页面，如果没有，则可以通过下面来获取：

  GET /gists/:id

如果我们要判断一个gists是否被收藏，可以使用：

  GET /gists/:id/star

创建Gists

  POST /gists

如果要创建一个用户自己的Gists库需要先进行身份验证，否则所创建库的创建者为匿名。
创建时提交的JSON数据结构如下：

{
  "description": "gist库的描述",
  "public": true,
  "files": {
    "file1.text": {
      "content": "文件内容，或者代码"
    }
  }
}

删除Gists

  DELETE /gists/:id

需要身份验证。

以上就是我们需要的所有端点(endpoint)。即使没有提供查询相关的API，但使用这些API来编写这个示例应用还是足够的。

分析每一项功能并列出相应的API端点(endpoint)或iOS功能都是必须的。我们要确保这些API是有效的，如果不是并且它们是由你们自己团队来维护的，那么赶快进行申请，以便留有充足的时间来实现这些API。

用户界面

接下来，我们来设计我们的应用以便让用户使用起来。我们将分析每一个任务并给出相应的使用方式。下面是我按照接口的使用对功能进行重新排序。

认证流程

当用户所操作的功能需要身份认证后才能使用时，那么首先我们将进行用户身份认证检查，如果没有通过，则启动登录流程让用户登录。

如果你的应用中有许多功能允许用户在未登录之前使用，那么或许你希望延迟用户的登录。因此对于哪些需要登录后才能调用的接口，你必须在调用之前检查用户是否登录过。

公共Gists列表

首页是公共Gist的列表(使用表格视图table view)。

我的收藏

从公共列表，用户可以切换到我收藏的列表。

我的Gists

从公共列表或我收藏的用户都可以切换到我的Gists。
上面三个列表很相似，是否我们可以使用一个带有选择器的表格视图，用户可以通过选择来切换这三种视图。

查看Gists详情

当用户在列表中点击其中一个Gists后，我们将转换到另外一个不同的视图。在这个视图中将详细的列出了Gists的信息(描述及文件名称)以及可以让用户查看文件的内容。同时，界面中也会显示我们是否已经收藏过该Gists。

收藏/取消收藏Gists

在详情页面中，我们将显示收藏的状态，并可以通过点击进行收藏或取消收藏。

新建Gists

在我的Gists列表视图的右上角有一个+按钮。点击这个按钮将显示一个录入表单，用户可以用来创建一个新的Gists，表单中需要录入的信息有：

• 描述：一段文本；
• 是否公开：布尔值；
• 文件名称：文本；
• 文件内容：文本。
  为了保持简单，1.0版中只允许在Gists中创建一个文件。

删除Gists

在我的Gists视图中可以通过滑动删除一个Gists。

检查你的功能列表并给出用户界面，以便用户可以完成这些功能。

API需求

当我们梳理这些用户功能时，会发现有些需求的API并不是那么明显。因此，我们需要仔细阅读，以便整理出一个列表清单。

认证

当未认证时，我们可以读取公共Gists，并可以匿名创建一个Gists。但是，当需要读取或编辑私有的Gists时，则必须进行OAuth认证。请参阅Github Gists API文档。

因此，我们需要对用户进行身份验证。对于集成，首选的是使用OAuth2.0。该接口使用了用户名/密码进行验证，但是我们不需要为这些敏感数据担心。因为，OAuth2.0不会让我们看到用户名和密码，而交互的只是用户的应用令牌(token)。我们将安全的保存OAuth的令牌。

检查一下你的API认证要求。在后面的认证章节我们会实现OAuth2.0认证、基于令牌的认证，以及最基础的用户名/密码认证。

设置Accept报头(Accept Header)

在Github API文档中描述到，我们必须设置请求的Accept报头，类似下面：

  Accept: application/vnd.github.v3+json

也就是说，你不设置的话，返回的结果将不是你所期望的。所以，我们会在后续的开发中进行处理。

查看你的API文档，确认还有哪些需要设置的。

在iOS9中，苹果引入了App Transport Security(ATS)概念，具体参见这里。 ATS要求使用SSL进行数据传输，这对实施来说是非常挑剔的。可悲的是，现在很多服务器是不满足这项要求的。但，GitHub的gist API是满足ATS这项要求的，因此我们不必添加额外的处理。

如果你在iOS9中调用自己的API出现了SSL错误，你需要添加ATS的错误处理。你可以在下一章节中看到如何解决的细节。你可以用章节中的代码尝试调用你的服务器所提供的一些简单API看是否有SSL错误。

制定开发计划

现在我们已经知道我们要做什么，以及怎么做。那么我们将逐步实现这些功能，从而完善这个APP。

• 创建我们的APP，并增加一个表格视图用来显示公共Gists列表；
• 增加自定义报头(header);
• 加载表格视图中的图片;
• 当用户滚动到底部时加载更多的Gists;
• 增加下拉刷新功能;
• 增加认证，让用户可以切换到我的Gists及我的收藏列表;
• 创建Gists的详情页面;
• 在详情页面增加收藏/取消收藏功能;
• 增加删除和新建功能;
• 增加无网络情况时的处理。

按实现的顺序列出你的视图及功能。尝试与Gists App的开发顺序进行匹配。如果你的API都需要身份认证才能够调用，那么你需要先跳到认证章节，然后再回来。如果你的所有请求都需要添加自定义报头，那么需要先跳到报头章节。

我们现在已经列出了应用的基础需求，也知道下面该怎么开始。但，在开始动手之前，让我们先花点时间了解一下在Swift中如何进行web请求，以及JSON解析，以免后面陷入这些细节之中。

 

大家可以关注我的微信公众号(CD826Workshop)来进行交流。

​