5

API的返回值形式

 2 years ago
source link: https://limboy.me/posts/api-return-format/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

API的返回值形式

2011-05-04

假设我们有一个 rest 服务，该 rest 服务会返回 json 格式的信息，以 twitter 为例：访问http://api.twitter.com/1/users/show.json?user_id=12345会得到如下结果：

{
	id_str: "12345"
	is_translator: false
	following: null
	profile_text_color: "333333"
	description: "ID 12345"
	status: {
		coordinates: null
		text: "Follow @ha
	}
	//...
}

这是一个正常用户的信息，如果访问一个不存在用户，会返回类似下面的结果

{
  request: '/1/users/show.json?user_id=12345111';
  error: 'Not found';
}

有没有发现，两次请求只是 userid 不一样，但返回形式却截然不同，这其实也不是什么大问题，客户端只要先检查一下是否有 error 这个 key，就能知道这次请求是否出错。不过我想了个另一个方法，能让返回形式有相同的结构。

借鉴了一下 http 协议，把返回结果分为 header 和 body 两部分，一个正常的请求会返回如下的信息

{
	'status' => 'ok',
	'content' =>
	{
		'blah' => 'blah',
		//...
	}
}

status 相当于 http 的 status 头信息，通过检查该信息可以知道请求是否正常，如果是'ok'则为正常，如为'error'则不正常，如果返回出错，则会在 content 字段里包含足够的错误信息

{
	'status' => 'error',
	'content' =>
	{
		'request' => 'http://...',
		'code' => 404,
		'message' => 'file not found',
	}
}

这里只包含了最基本的 3 项信息，request 指代的是本次请求的 url，code 类似 http 状态码，message 指代出错信息。

这样是不是更优雅些？


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK