下载掌阅APP，畅读海量书库
立即打开
正如本书1.4节所讨论的，我们需要对示例中的不同接口进行定义。请记住，这个例子是一个微博应用，它允许用户自己撰写博文，以供其他人阅读。
在这个例子中，有两个主要的接口：
❍一个HTML接口，允许用户使用浏览器与服务端进行交互。
❍一个RESTful API，允许创建其他客户端，如智能手机App。
接下来讨论第二个接口的设计。我们首先将对各种基本概念和所要使用的资源进行描述：
❍ 用户 （user）：代表应用程序的用户。它将定义为一个用户名和密码，用于登录系统。
❍ 博文 （micropost）：由用户发布的最多包含255个字符的小段文字。可以选择将博文发给用户。博文包含其创建时间。
❍ 博文列表 （collection）：用户博文的集合。
❍ 关注人 （follower）：用户可以关注其他用户。
❍ 时间线 （timeline，亦称时间轴）：按序排列的被关注用户的博文列表。
❍ 搜索 （search）：允许搜索用户，或搜索博文中的文字。
我们可以用RESTful的方式将这些元素定义为资源，就像本章前面介绍的那样，首先是URI速览：
请注意，我们为/token添加了POST和DELETE资源，以处理登录和注销操作。
完成这个简单的设计之后，接下来就是定义每个端点。
我们将按照本章前面介绍的模板来详细描述所有的API端点。
登录：
❍ 描述 ：使用适当的认证凭据，返回一个有效的访问令牌。该令牌作为Authorization（授权）头部信息包含在请求中。
❍ 资源 URI：/api/token
❍ 方法 ：POST
❍ 请求正文 ：
❍ 返回正文 ：
❍ 错误 ：
注销：
❍ 描述 ：将访问令牌作废。如果操作成功，则返回204 No Content错误。
❍ 资源 URI：/api/token
❍ 方法 ：DELETE
❍ 错误 ：
❍ 头部信息 ：Authentication: Bearer: <token>
检索用户：
❍ 描述 ：返回用户名资源。
❍ 资源 URI：/api/users/<username>
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 查询参数 ：
❍ 返回正文 ：
❍ 错误 ：
检索用户的博文列表：
❍ 描述 ：以分页的形式返回某用户所有博文的列表。
❍ 资源 URI：/api/users/<username>/collection
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 返回正文 ：
❍ 错误 ：
创建新的博文：
❍ 描述 ：创建一篇新的博文。
❍ 资源 URI：/api/users/<username>/collection
❍ 方法 ：POST
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 请求正文 ：
❍ 错误 ：
检索博文：
❍ 描述 ：返回指定ID的一篇博文。
❍ 资源 URI：/api/users/<username>/collection/<micropost_id>
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 返回正文 ：
❍ 错误 ：
更新博文：
❍ 描述 ：更新指定ID博文中的文字。
❍ 资源 URI：/api/users/<username>/collection/<micropost_id>
❍ 方法 ：PUT，PATCH
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 请求正文 ：
❍ 错误 ：
删除博文：
❍ 描述 ：删除指定ID的一篇博文。如果成功，则返回204 No Content错误。
❍ 资源 URI：/api/users/<username>/collection/<micropost_id>
❍ 方法 ：DELETE
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 错误 ：
检索用户的时间线：
❍ 描述 ：以分页的形式返回用户时间线上所有博文的列表。博文将按照时间戳的顺序返回，时间最久的最先返回。
❍ 资源 URI：/api/users/<username>/timeline
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 返回正文 ：
❍ 错误 ：
检索某个用户所关注的用户：
❍ 描述 ：返回所选用户关注的所有其他用户的列表。
❍ 资源 URI：/api/users/<username>/following
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 返回正文 ：
❍ 错误 ：
关注某用户：
❍ 描述 ：让指定的用户关注另一用户。
❍ 资源 URI：/api/users/<username>/following
❍ 方法 ：POST
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 请求正文 ：
❍ 错误 ：
取消关注某用户：
❍ 描述 ：取消关注某个用户。如果成功，则返回204 No Content错误。
❍ 资源 URI：/api/users/<username>/following/<username>
❍ 方法 ：DELETE
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 错误 ：
检索关注某用户的其他用户信息：
❍ 描述 ：以分页形式返回所有关注该用户的用户列表。
❍ 资源 URI：/api/users/<username>/followers
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 返回正文 ：
❍ 错误 ：
搜索博文 ：
❍ 描述 ：以分页的形式返回符合搜索条件的博文。
❍ 资源 URI：/api/search
❍ 方法 ：GET
❍ 头部信息 ：Authentication: Bearer: <token>
❍ 查询参数 ：
❍ 返回正文 ：
❍ 错误 ：
针对新的API所采用的这种先描述、再设计的“两步法”，让你能够迅速地看到设计过程中是否有问题。然后再对其进行迭代，直至问题得到修复。下一步要做的是开始实现所设计的API，我们将在后续章节中看到。