精华 客户端 API 开发总结
发布于 9 年前 作者 i5ting 19183 次浏览 最后一次编辑是 8 年前 来自 分享

既然有人看,那咱就分享一下

API 标准写法

摘抄:http://www.startupcto.com/backend-tech/building-an-api-best-practices

You’ll generally want to wrap all your API responses in an ‘envelope’ which specifies metadata about the APIcall.

// sample JSON envelope
{
  "status": {
    "code": 10000,
    "message": 'Success'
  },
  "response": {
     ...results...
  }
}

Doing this allows for client handler code to behave the same way for all API calls, since it gets a responses back in a universal format.

语义上再好一点,推荐:

// sample JSON envelope
{
  "status": {
    "code": 10000,
    "message": 'Success'
  },
  "data": {
     ...results...
  }
}

可视化编辑校验: http://jsoneditoronline.org/

注意事项

  • json一定要规范,不然ios的json库无法读
  • 如果支持jsonp,自己再加上一个callback就可以了。
  • 状态码说明:code:10000类似的,要以业务或者功能模块来分类,以便debug的时候快速定位
  • 尽量遵守rest

解释一个问题

http://ruby-china.org/topics/15164#reply5

xiaogui 7楼 , 19小时前  喜欢 
#5楼 @lytsingsun 
先说几点个人建议吧:
1、返回 json 数据,最好外面包一层校验,能让客户端快速知道,这数据合不合法、是否有错;
2、代码复用方面,主要看你项目的实际情况;
3、最好是能给客户端进行充分的沟通,怎么让双方都正规还方便;
4、性能方面,不外乎负载均衡、上缓存、数据库读写分离、代码优化;

第一点:就是说上面返回的status,要有code和message,根据code来判断问题,一般会直接alert出来code:message或者在日志里

这是xiaogui说的外面包一层校验的意思

其他的就没啥需要特殊说明的了

关于http的状态码和api里的status.code说明

http的状态码是直接在request里的,这个一般指服务器的状态,api是假设每一个请求都是200的,在客户端非200的请求统一处理异常,而200的请求,首先解读status获取code是否为0(假设0是请求正确返回),如果是0就读取data,继而完成相应业务逻辑处理。

  • 职责单一,该是server的就是server,该是业务逻辑的就是业务逻辑的
  • 少用http状态码,把http状态码统一封装到一个类,用于处理异常情况(ajax也好,ios的asi或afnetworking也好)
  • 同样可以表示状态的,优先自定的状态码

为什么在response json里没有必要加http status code

每一个request都可以获得状态码,而上面我给出的json是在response里,那么在在http请求完成的时候我们仍然可以获得此request的所有信息

如果仍然在response里加入request里的东西,这样做是重复的,真的是没有必要的,not DRY

换个角度讲,一般我们使用http库的时候要自己封装处理http status code的,尽力减少每个请求的代码,是不可能每个request都去

判断code==200.。。。。。然后。。。。。

技术选项

  • express or koa
  • rails-api
  • grape
  • sinatra
  • go的类似sinatra的框架beego

开发最佳实践

  • api的code和msg可以写一个模块,直接继承到api里
  • api测试和mock,最好是可以先mock出静态的,可以api和mobile端同时开发
  • 根据测试生成api文档

不过我还没有发现好的实现,还请各位指点

api的最佳实践

还是看open api吧


当。。。。

关联优先

比如获取新闻接口返回数据如下:

{
	"data": [
		{
			"nid": 2,
			"mid": 1,
			"text": "this is a test.",
			"images": [
				"http://121.199.40.172:8086/images/news/12.png",
				"http://121.199.40.172:8086/images/news/13.png",
				...
			],
			"videos": [
				"http://121.199.40.172:8086/videos/news/12.amr",
				"http://121.199.40.172:8086/videos/news/13.amr",
				...
			],
			"like": 0,
			"comment": 0,
			"publish_time": "2013-01-01 12:30:10"
		},
		...
	],
	"status": {
		"code": "0",
		"msg": "success"
	}
}

返回的对象数组,乍看是合适的,但是我们发现1条新闻对应着多个评论,如果评论没有出现在此接口中,我就要发一个新的请求,这样问题就来了,该不该呢?

个人觉得,好的api,如果一次news的数据不是特别多,就应该最新评论,如5条,10条的带上

更新: 使用cors解决跨域问题

使用cors,解决跨域问题,实际中也是这样用,不过app.js里配置的路由还需要更严谨

// 支持跨域
app.use(require('cors')());

一般移动测试都要起一个server,然后访问api服务器的时候就要跨域,这样就可以在移动端浏览器里测试了。

而phonegap打包的时候是本地html所以不用跨域,但是为了测试方便,服务器还是建议加上cors。


这是去年我在ruby-china发的总结,转过来给大家看看

原文地址:https://ruby-china.org/topics/15173

欢迎关注我的公众号【node全栈】 node全栈.png

20 回复

node版本之后再改吧

原来是楼主刚刚写的,厉害厉害~

感觉如果不是有特殊的业务需求 新闻的评论还是跟内容分开的好

@hxors 是的,但大部分客户端都要显示最近10条评论或热评的,这种情况躲不开

我个人更倾向于分开加载 可能用户需要先通过看内容来确定是否感兴趣 再决定是否看更多相关的东西😊

@hxors 分开加载更加灵活点吧,不过有时候会为了特别的需求会添加点东西,不考虑性能和流量的话,不打紧~ 接口最需要做好的就是充分考虑兼容性

@i5ting 已收藏,楼主CNode活跃分子,实力非一般~

屌,刚好最近在搞这个

我也写过客户端的API,但是没有这么规范,可能是我本身不是搞后端的吧,自己开发app,也只能自己来写rest api

好多后台一出错就丢个html过来 不多说都是泪

@gwesley 哈哈,鄙视那帮人,404都不给返回json。。。。。

@i5ting http://jsoneditoronline.org/ 这个站点是开源的么? 正想找这样的编辑器

@chapgaga 傻了吧

[sudo] npm install -g je

然后运行 je

哥很久之前就写好 的

@i5ting 代码没有放github上? 怎么和那个站一模一样,那个站是你做的?

终于得空写了res.api, 用法见 https://cnodejs.org/topic/55818a0c395a0c1812f18273

如果按照这个约定走,代码还是比较简单的,还可以抽象的是返回码的地方,但res.api是一个小中间件没必要做更复杂的事儿,api能渲染好就不错了

楼主方便给个QQ交流一下嘛

JSON API 设计参考文档,英文版1.0已经于近日完成 http://jsonapi.org/

中文版 文档还停留在2013年 http://jsonapi.org.cn/format/

@SoaringTiger 它是纯restful的api,对于客户端并不友好的

回到顶部