通 用 接 口 说 明

目的

为了规范各个接口之间的共性内容，向前端开发者介绍接口用法，特设定该文档。API 接口只提供纯数据输出或者写行为，不包括样式或者模板呈现。接口不限定特定的客户端或服务端，使得 Android/iOS 客户端/HTML5/WindowPhone 和后台 WebService 数据操作均可适用，但某些情况下，会根据客户端提供 UserAgent（简单说，UserAgent 是客户端标识，说明“来者何人”，是什么的客户端） 进行适配。总的来说调用接口遵循以下原则。

• HTTP 协议通信和 JSON 数据格式，其响应 ContentType 为“application/json”
• URL 面向资源设计，即采用 HTTP RESTful 之风格
• 字符使用 UTF-8 编码

其中，JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。它基于JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999 的一个子集。JSON 提出者是 Douglas Crockford。RESTful 之风格，含状态传输（英文：Representational State Transfer，简称 REST），采用客户端/服务器模式，建立在分布式体系上，通过互联网通信，具有高延时（high latency）、高并发等特点。RESTful 架构是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用。

所谓接口，直观来说是呈现如下截图的 JSON 数据。

顺手的调试工具是成功开发的一半，下面请让我们了解一下调试工具如何。

调试工具

虽然 curl 命令行工具就可以请求远端服务器，但推荐使用更直观的 GUI 工具，如 Firefox 下的插件，如下所示。

JSON结果查看插件：JSONView、JSON-handle如插图所示。

HTTP 请求发送工具：Poster，如插图所示。

HttpRequester，如插图所示。

路由规划

过去的 API 规划中，单笔新闻的 URL 比较常见的是使用问号加参数的形式，如 /news/?id=1000。但这里建议的写法则是 /news/1000。在 RESTful 语境中，一切都被认为是一种资源。而每个资源皆由 URL 标识。其命名方式总是以“http://主机名:端口+/二级目录（或可省略）+/实体1+其他操作的形式来拼装最终的 URL，例如 http://localhost:8080/myproject/news，其中 news 为读取新闻列表的接口。我们忽略 URL 前缀，简单说明接口的用法：

• GET /news             // 请求新闻列表，返回一笔或多笔新闻，或 null
• GET /news/1000   // 返回 id 为 1000 的新闻纪录，单个新闻的完整信息

尽管取消了如 ?id=XXX 的写法，但是“问号加参数的形式”依然得到保留。为了满足复杂的查询要求，列表操作还支持分页参数，以及传入多种条件和排序参数进行查询（如下所示）。

• GET /news/?start=0&limit=5              // 读取实体列表，指定分页参数 start=0&limit=5
• GET /news/?catalog=company_news // 读取实体列表，指定参数为 catalog=company_news，返回所有不分页；
• GET /news/?catalog=company_news&start=0&limit=3  // 读取实体列表，指定参数为 catalog=company_news，分页
• GET /news/…… ……                // 更多的查询手段。

CRUD API

上述我们着重讨论获取信息行为，也就是 GET、读的操作。至于写的操作（创建、修改），会与前面提到的接口重叠，但 HTTP 方法和提交的内容不同。于是我们看到 URL 仍是 /news，但 HTTP 方法将是：

• PUT    /news            // 创建新的新闻
• POST  /news/1001  // 修改 id 为 1001 的新闻

RESTful 语境中 HTTP 方法即是对资源操作的谓词，分别是 GET/POST/PUT/DELETE 涵盖了各种读写操作，它们具体说明如表格 3所示