express－20 REST API和JSON

简介

• “Web服务”是一个通用术语，指任何可以通过HTTP访问的应用程序编程界面（API）; 我们的重点是提供“REST风格”的服务，与其交互要更直接得多。
• REST表示“表述性状态传输”（Representational State Transfer）， REST的正规描述很复杂，需要计算机科学形式上的表述，但REST基本上就是客户端和服务器端的无状态连接。
• REST的正式定义还指出服务可以被缓存，可以被分层（即当你使用一个REST API时，可能还有其他REST API在它下面）。
• 从实用角度来看，因为HTTP的限制，实际上很难创建出非REST风格的API;

JSON和XML

• 提供API的关键是有相通的语言;通信部分已经决定了，必须用HTTP方法跟服务器通信。但在那之后，我们可以用任何数据语言。
• 传统上XML是非常流行的选择，并且是很重要的标记语言。
• 尽管XML不是特别复杂，但Douglas Crockford觉得还可以做得更轻量，因此JavaScript对象标记（JSON）诞生了。
• 除了对JavaScript非常友善（但它绝不是专有的，它是任何语言都可以解析的简单格式），它还有个优势，即一般手写起来也比XML更容易。

我们的API

• 在实现之前，我们会先把API规划好。

  • GET /api/attractions: 获取景点。以lat、lng和radius为查询字符串参数，返回一个景点列表。
  • GET /api/attraction/:id: 根据ID返回一处景点。
  • POST /api/attraction: 以lat、lng、name、description和email为请求体添加新的景点。新添加的景点会进入一个待审批队列。
  • PUT /api/attraction/:id: 更新一处已有的景点。参数为景点的ID、lat、lng、name、description和email。更新会进入待审批队列。
  • DEL /api/attraction/:id: 删除景点。参数为景点ID、email和reason。删除会进入待审批队列。
• 可以有很多描述API的方式。这里选择用HTTP方法和路径的组合来区分API调用，并用查询字符串和请求主体参数混合的方式传递数据。
• 作为选择，可以用方法全都相同的不同路径（比如/api/attractions/delete）;也可以用同一种方式传递数据。比如可以选择在URL中用查询参数而不是查询字符串传递所有必需的信:GET/api/attractions/:lat/:lng/:radius
• 为了避免出现超长的URL，建议用请求主体传递大块数据。

• POST用于创建而PUT用于更新（或修改），这已经成为标准了。

API错误报告

• HTTP API的错误报告一般是通过HTTP状态码实现的：
• 如果返回的响应码是200（OK），则客户端知道请求成功了；
• 如果响应码是500（服务器内部错误），则请求失败了。
• 然而在大多数应用程序中，并不是所有事情都可以（或者应该）粗略地划分成“成功”或“失败”。比如说，用ID请求某件东西，但如果那个ID不存在怎么办？这不是服务器错误：客户端请求了不存在的东西。
• 一般来说，错误可以分为以下几类: