通 用 接 口 说 明-阿里云开发者社区

开发者社区> 开发与运维> 正文

通 用 接 口 说 明

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

目的

为了规范各个接口之间的共性内容,向前端开发者介绍接口用法,特设定该文档。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结果查看插件:JSONViewJSON-handle如插图所示。

HTTP 请求发送工具:Poster,如插图所示。

HttpRequester,如插图所示。

路由规划

过去的 API 规划中,单笔新闻的 URL 比较常见的是使用问号加参数的形式,如 /news/?id=1000。但这里建议的写法则是 /news/1000。在 RESTful 语境中,一切都被认为是一种资源。而每个资源皆由 URL 标识。其命名方式总是以“http://主机名:端口+/二级目录(或可省略)+/实体(一般以英文单数形式)+其他操作的形式来拼装最终的 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/…… ……                // 更多的查询手段。

上面只是针对实体对象。与关系型数据库中的“关系”类似,我们架构中存在着一种“关联对象”,例如新闻文章的配图 img,属于关联对象性质(关于结果输出的一点提示:如上所述,尽管实体对象和关联对象在路由规划层面有明确的划分,但 API 最终输出中不是强制分开的。有时出于减少 HTTP 请求的考虑,或者对象之间关联性较强,则可以将被关联对象合并到同一个接口中输出),于是我们可以通过这样的形式访问:

  • GET /news/img    // 读取实体下面所有的关联对象的列表,凡是 img 属于 news 的,都会列出
  • GET /news/img/11  // 返回 id 为 11 的新闻图片,显示该图片的详细信息
  • GET /news//img?size=small // 支持复杂查询,这点不管对于实体对象还是关联对象皆是适用的。

关联对象并不具备单独接口,所以不存在如 /news/img 的接口。于是,创建、修改关联对象时候,分别是 POST news/img(创建),/news/img/10002(修改、删除)。
上述我们着重讨论获取信息行为,也就是 GET、读的操作。至于写的操作(创建、修改),会与前面提到的接口重叠,但 HTTP 方法和提交的内容不同。于是我们看到 URL 仍是 /news,但 HTTP  方法将是:

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

提交内容每种业务对象都不相同——这不属于本文档讨论范围。关于各种请求方法,参见下一小节。

CRUD API

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

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

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

HTTP方法
对应 CRUD 操作 读行为/写行为
GET        /uri/xxx 查看 Read,获取列表或单个实体 只读行为
POST      /uri/xxx 改 Update,修改实体内容 写行为
PUT        /uri 增 Create,新建一个实体 写行为
DELETE /uri/xxx 删 Delete,删除某条记录 写行为

CRUD 即“增、删、改、查”,也是与后端数据库一一对应。

创建操作可以使用 POST,也可以使用 PUT,区别在于 POST 是作用在一个集合资源之上的(/uri),而 PUT 操作是作用在一个具体资源之上的(/uri/xxx),再通俗点说,如果 URL 可以在客户端确定,那么就使用 PUT,如果是在服务端确定,那么就使用 POST,比如说很多资源使用数据库自增主键作为标识信息,而创建的资源的标识信息到底是什么只能由服务端提供,这个时候就必须使用 POST。

本文档所讨论的是基础模块。不同的业务对象,有不同的表和 SQL,也有不同的 Service,但接口层应该尽可能复用,如上述的复杂查询,无论实体对象还是关联对象都可用——即是一例。但某些子对象不能复用 SQL,要为其特别地写,如 /user/updatePassword。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章