# File API

# 接口概述

FileAPI旨在存储、管理文件。上传到FileAPI的文件会产生持久化的链接（或也可以认为是文件的唯一id）

# 文件上传

PUT "/file" @returns Response<File>

上传协议完全符合HTTP的multipart/form-data的上传方式，可使用如下命令直接测试：

curl -XPUT -F file=@local-file.txt "http://example.com/file?access_token={token}"

可指定 secure={boolean} 参数，来指定下载文件时是否需要token控制，具体可参考后续安全文件章节说明

# 文件下载

GET "/file/{id}" @returns <文件流>

默认情况下可免token，此链接可直接提供给浏览器使用（用于下载、图片显示等）
安全方式需要给出access_token，具体请参考后续“安全附件”章节。

# 文件修改

POST "/file/{id}" @returns Response<File>

文件修改，相当于重传但保持id，格式与上传相同

# 文件删除

DELETE "/file/{id}"

# 文件meta信息查询、管理

GET/POST "/file/{id}/meta" @returns Response<File>

获取或修改该文件的meta数据，包含文件名、创建日期、修改日期、文件大小等
举例：

curl -XPOST -d '{"meta":{"secure":true,"token":"********"}}' "http://example.com/file?access_token={token}"

可在meta中指定需要生成的缩略图尺寸

# 缩略图

* GET "/file/{id}/thumb/{size}" @returns {文件流}

下载缩略图，size格式为"NxM"。（如无该尺寸，则就近匹配？）

# 数据结构

// TYPE {file} 
{
    "mime":{string},                      // 文件类型，未知二进制类型为"application/octet-stream", 参见MIME types定义。
    "size":{integer},                     // 文件大小，单位byte
    "createTime":{long},                  // 创建日期
    "lastModified":{long},                // 最后修改日期
    "thumbsizes":["n1*m1","n2*m2",...],   // 获取或指定上传的文件需要生成以下规格的缩略图，最多允许5张，如果比例和原比例不同，则会拉伸。缩略图大小不会超过原图，同时不会超过1024x768
    "sha1Hash":{String}
    "tags":{string},                      // 逗号分隔的字符串
    "meta":{
       "secure":{boolean},
       "token" : {string},               // token内容
       "tokenExpire" : {long},           // token超时时间，Unix时间戳
       "tokenDisposable" : {boolean},    // 是否一次性，默认false
       ...
    },
    "id":{guid},
    "name":{string},                      // 文件名
    "kind":"canvas.file",                 // 常量
    "uri":{uri},                          //文件下载地址

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

其他参考：

http://en.wikipedia.org/wiki/Internet_media_type
http://www.ietf.org/rfc/rfc2046.txt

# 安全文件

# 背景

FileAPI提供的下载链接默认是匿名的，任何人知道链接即可访问。这在非HTTPS、链接被分享扩散情况下，存在一定的安全风险
可对单独文件设置为“安全的”，其语义是：下载该文件必须先提供一个token
token可分为三种，可分别支持服务端/客户端获取、限时/限次、要求登录等功能
201803新增

# 规范

对于单个文件，可设定 meta.secure = true ，含义为下载时必须在 url 中给出 access_token。可通过如下方法设置：

PUT /file?secure=true
POST /file/{id}/meta

其他 meta 参数：

{
  "secure" : {boolean},     // 是否验证token，默认false
  "token" : {string},       // token内容
  "tokenExpire" : {long},   // token超时时间，Unix时间戳，仅适用于自管token
  "tokenDisposable" : {boolean}, // 是否一次性，默认false，仅适用于自管token
}

1
2
3
4
5
6

三种 token

应用授权的oauth的token
应用场景是：应用负责变更最终交付给用户的下载链接。不允许浏览器直接下载。
适用于应用本身有足够知识精确保护的情况，可提供最大的安全性
此场景的限制是：需要服务端导流量、需高度定制化使用
用户授权的oauth的token
应用场景是：与上面场景相似，但可做下载审计。不允许浏览器直接下载。
此场景的限制是：需用户授权
FileAPI自管token
应用场景是：调用FileAPI生成token可用于前端直接使用
可通过时间戳或次数保障链接分享不带来安全问题
此场景的限制是：链接刷新后失效。