API的设计困难 求协助 求指导

[lookhi]

现在在设计我们有爱帖的网页快照API.
共3个调用.
1. 请求网页快照，这个简单
2. 查询快照状态，因为快照需要时间。现在还不是立即就可以获取，因此增加这个查询步骤。
3. 获取快照的数据，这样就可以把快照的数据保存到合适的地方或者放到其他网站上进行展示。

问题出在第3个 获取快照的数据 上。
现在是这样设计的
调用:
HTTP地址: https://www.youaitie.net/api/getsnapshot/
请求方式: GET
调用参数:
token → 您的请求访问许可(access_token)。
jobid → 提交快照请求时返回的jobid值

但是返回数据结果有麻烦了。这里有2种情况。
1) 提交的参数有问题，那么只能返回一个错误提示和错误原因回去。
2) 提交的参数都正确，需要返回一个数据文件回去。

这2种情况怎么来区分开来？分别返回什么样的结果给请求方，而且调用的请求方还能很方便的进行区分出这2种情况。

[yexiaoxing]

统一用json，写一个resultid，请求方通过判断resultid来知道是否发生错误。

[allenwei]

参数有问题就返回500或者其他状态码，在body里面写错误信息

[lookhi]

@yexiaoxing json里面包含一个数据文件 膨胀太多了的
@allenwei 是个好主意啊

[lookhi]

刚刚在线更新API的文档，先文档后实现. http://www.youaitie.net/api.html
是否说明清楚了啊？

[siteshen]

为什么不用http自带的staus表示成功与否？
参数错误：400，access_token不正确或过期：401？

[lookhi]

@siteshen 也想过考虑这样更标准的status code.
不过有些错误原因,status code里面是没有覆盖的。比如任务还未完成。
用这40x系列的错误提示，用户还是需要去看body里面的内容。而且还需要针对不同的status code进行分类。
当然还有个停重要的原因，40x系列的status code已经被http服务器这边重新定义到一个自定义的错误页面上。也不想造成同code不同显示的困扰。
还有个问题，API说明清楚么 我对自己写的这个文档的表达水平很是担忧啊.

[sprhawk]

@lookhi 最方便的其实就是自己定义返回status code，你的接口是的错误返回应该和web请求的返回分离，如果真的出现40x错误，api请求也不应该直接跳转到web页面上。

另外，我觉得你可以单独使用，但我还是建议你混合使用：通过你返回的content-type，你可以确定你的文档类型，如果是json，就调用json的处理方法（判断错误之类），如果是其他的类型（比如xml），那就当作是正确的返回，继续处理好了

[sivacohan]

我们的做法是不使用status code，理由是避免和服务器的问题产生混淆。
用json，每一个json的格式为，errcode，errmsg，body，得到返回判断errcode是否为0，不然就log errmsg，然后进行相关处理

[lookhi]

@sivacohan 这个是需要下载数据。数据文件可能有个十兆几十兆的，JSON里面包含这么大的一个数据集。可以吗？

[alexrezit]

不一定所有东西都放在内容里面, status code 放在 header 里面才是适合你的方法.
而且大数据应该和 API 分离, API 只返回一个数据文件的 URL, 需要数据文件时当作单纯的下载来处理.

[alexrezit]

@sivacohan
在 header 里面加一个临时 token 即可, 如果服务器出错没有返回正确的值直接抛弃掉. 据说还能顺便防范一下 CSRF 攻击.

[lookhi]

@alexrezit 那用户还需要额外的一次数据请求吧。同样的这个额外的请求 依旧会遇到非法读取或者过期 未完成的问题吧.

[sivacohan]

@lookhi

设计接口有一个我个人非常喜欢的原则，只返回正确的结果，不对就抛出异常。

返回的URL应该做如下处理。

1、检测资源合法性。
2、生成有时间限制的临时性URL，防止URL被滥用

[alexrezit]

@lookhi
那就跟这个 API 没关系了, 按你的思路把所有数据一次性全部拿到耦合度太高.

[lookhi]

@sivacohan @alexrezit 刚去看了下百度的云存储API，发现也是这样的。
下载一个a.torrent文件.

下一个不存在的文件a.avi & Token错误
curl -I "https://pcs.baidu.com/rest/2.0/pcs/file?method=download&access_token=3..2592000.1367840158.2856296-248413&path=%2Fapps%2F%E6%B5%8B%E8%AF%95%E5%BA%94%E7%94%A8%2Fa.avi"

HTTP/1.1 401 Unauthorized
内容为{"error_code":110,"error_msg":"Access token invalid or no longer valid","request_id":2789237462}

下一个不存在的文件a.avi
不存在的情况
HTTP/1.1 404 Not Found
内容{"error_code":31066,"error_msg":"file does not exist","request_id":1463975029}

下载a.torrent
正确的请求
HTTP/1.1 200 OK
直接返回数据