第2章端点的设计与请求的形式.PDFVIP

第2章 端点的设计与请求的形式 从本章开始，我们将讲解API 具体的设计规则及方法。对外公开Web API 时， 必须首先思考将怎样的信息或数据经由怎样的API 对外公开。接下来就让我们来考 虑一下如何决定对外公开的功能和端点，以及Web API 的端点该如何设计。 2.1　设计通过 API 公开的功能 对外公开API 时，首先必须决定将怎样的内容经由API 来公开。假设我们需要 开发一个非常简单的SNS 在线服务，那么就来思考一下应该如何设计和开发服务所 需的Web API 。表2-1 中列出了SNS 在线服务的功能清单。该SNS 在线服务可以通 过Web 或者移动客户端应用进行操作。我们希望将要公开的Web API 不仅可以让自 己开发的移动应用使用，而且需要进一步扩大公开的范围，让其他用户也可以使用。 表 2-1　SNS 在线服务的功能 功能 用户注册、编辑 搜索、添加、删除好友 好友之间的消息交互 在这种情况下，需要准备怎样的API 才能满足我们的需求呢？ 一种非常简单的API 设计方法是编制一套数据访问机制，它能够直接操作在线服 务所用的数据库及其数据表里的信息。比如前文提及的SNS 在线服务中会在其数据 库里用三张数据表来分别存放用户信息、好友的关系网信息及时间轴信息。如果API 22 第2 章　端点的设计与请求的形式 能对其进行搜索、编辑等操作，就意味着它几乎可以做到SNS 在线服务所需的功能。 但如果仅通过封装SQL 语句来进行API 的设计，那么开发出来的API 会非常 难用。因为对于这样的API ，如果人们不理解其内部数据如何存放、数据之间存在 怎样的关系，就无法正确使用。并且这样的设计还会将服务内部数据的存储结构公开， 从安全角度来说存在很大的风险。因此，API 必须在更高的层次来描述相关的功能。 那我们该如何设计API 呢？首先，需要知道用户会如何使用对外公开的API ， 仔细思考用户的用例场景。现在我们需要设计的是面向移动应用的后端并向第三方 开放的API 。关于面向第三方的用例场景，因为我们难以知晓会有哪类用户以何种 目的来调用API ，所以这里暂且不谈，让我们首先思考一下用于移动应用后端的情景。 因为目的明确，所以设想业务情景也会比较简单。 面向移动应用的 API 所必备的功能 设计API 时，首先我们需要思考移动客户端应用的页面及各个页面之间的切换。 现在需要开发的SNS 应用很简单，我们可以设想整个页面及页面切换如图2-1 所示。 在该应用里，出于简化考虑，预设只需单方面添加对方为好友，无需对方确认即可 完成好友关系的建立。另外，至于向他人多大程度地开放时间轴、社交关系网、个 人信息等，该应用里也不会存在相关的配置。假设除邮箱地址及密码之外，其他所 有信息基本上都能被他人访问。 图 2-1　简单的 SNS 在线服务的移动应用的页面及页面之间的切换 2.1　设计通过API 公开的功能 23 让我们结合以上页面切换信息，来思考需要通过API 提供哪些功能。可以得出 以下列举的几点。 用户注册 登录 获取自身信息 更新自身信息 获取用户信息 搜索用户 添加好友 删除好友 获取好友列表 搜索好友 发送消息 获取好友的消息列表