跳到主要内容

简介​

Baitech 提供了 HTTP API 以支持用户使用 Baitech 的服务。在 “一主多端” 的架构下，Baitech Storage 和 Endpoint 都部署了 HTTP API 以提供不同类型的服务。根据自身职能不同，两者的 API 也采取了不同的认证机制。

具体来讲，

  • Baitech Storage 提供除 pinFile / pinByHash 等文件上传功能之外的所有 API，采用 API Key 作为认证机制。
  • Endpoint 提供 pinFile / pinByHash 等文件上传 API，采用 OAuth2 认证机制。

Baitech Storage​

API Key​

API Key 是 Baitech 的基础认证机制，用户注册成功后，系统会自动为用户生成 API Key。用户登录后可以在 个人面板 -> API -> API JWT 中查看。

每一个 API Key其实是一个 JWT Token，它代表用户来认证并访问 Baitech API。请务必保管好您的 API Key，不要与他人分享。

调用 Baitech Storage API​

Baitech Storage API 的 Base URL 为：https://api.decoo-cloud.cn

作为身份认证，您需要在调用 Baitech API 时将您的 API Key 按照以下格式包含在 Header 中：

"Authorization": "Bearer <YOUR_API_KEY>"

您可以使用 curl 命令测试 API 的连通性及您 Token 的有效性：

curl -X GET "https://api.decoo-cloud.cn/ping" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

如果调用成功，该请求会返回状态码200及如下消息体：

{
  "Success": true
}

如果调用失败，则会返回：

{
  "Code": 401,
  "Message": "Invalid token"
}

Endpoint​

Endpoint 列表​

Client 可以调用 Baitech Storage API 获取 Endpoint 列表：

curl -X GET "https://api.decoo-cloud.cn/endpoint/list" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

返回值如下：

 [
   {
     "id": 1,
     "name": "上海",
     "apiHost": "https://api-sh.decoo-cloud.cn"
   },
   ...
]

Access Token​

Endpoint 使用 Access Token 来验证用户的 API 请求。Access Token 由 Baitech Storage 签发，也同样由 Baitech Storage 来验证。具体流程如下：

  1. Client 调用 Baitech Storage API，申请 Access Token
  2. Client 调用 Endpont API，附上 Access Token 作为认证信息
  3. Endpoint 收到 Client 请求后，调用 Baitech Storage API 来验证 Access Token 是否有效。如果有效，则认证通过，继续处理 Client 请求；否则，返回 401 错误。

另外，Access Token 的有效期为2个小时。Access Token 过期后，Client 应该调用 Baitech Storage API 申请新的 Access Token。

申请 Access Token：

curl -X GET "https://api.decoo-cloud.cn/oauth/accessToken" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json"

数字签名​

在调用 Endpoint 的 pinFile 或者 pinByHash API 上传文件时，用户需要同时附上自己的 数字签名，以证明该文件确实由该用户上传。数字签名 由用户的 RSA 私钥对文件 CID 进行加密生成。Baitech Storage 将使用用户的 RSA 公钥对签名进行验证。

获取 RSA 私钥​

用户在 Baitech 注册成功后，系统即自动为用户生成 RSA 私钥。用户登录后可以在 个人面板 -> API -> 私钥 中查看。

获取待上传文件的 IPFS CID​

用户可以有多种选择获取文件的 IPFS CID。通常建议的做法是本地安装 IPFS Desktop，然后调用本地 IPFS 节点的 /api/v0/add HTTP API 来获取文件的 CID (注意：在调用该 API 时，建议将 only-hash 参数设为 true)。

如果您的 Client App 是基于 JavaScript 开发，一个更好的建议是直接使用 ipfs-core。它提供了更加轻量级和更加友好的方式帮助您获取文件的 CID。实际上，Baitech 提供的 Client SDK 中的 getFileHash 即是基于 ipfs-core 构建。

生成 数字签名​

关于如何使用 RSA 私钥和文件 CID 生成数字签名，如果您使用的编程语言是 JavaScript，可以参考 Baitech SDK 中的 相关代码。

其它常见编程语言的示例代码如下：

/**
 <dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
  </dependency>
 */

import org.apache.commons.codec.binary.Base64;
import javax.crypto.Cipher;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;

public class SecretGeneratorSample {
    private static final String CHARSET = "UTF-8";

    private static final String RSA_ALGORITHM = "RSA";

    private static final int KEY_SIZE = 1024;

    public static String generateSecret(String cid, String key) throws Exception {
        PKCS8EncodedKeySpec pkcs8KeySpec = new PKCS8EncodedKeySpec(Base64.decodeBase64(key.getBytes(CHARSET)));
        KeyFactory keyFactory = KeyFactory.getInstance(RSA_ALGORITHM);
        PrivateKey privateKey = keyFactory.generatePrivate(pkcs8KeySpec);
        Cipher cipher = Cipher.getInstance(keyFactory.getAlgorithm());
        cipher.init(Cipher.ENCRYPT_MODE, privateKey);
        return new String(Base64.encodeBase64(cipher.doFinal(cid.getBytes(CHARSET))), CHARSET);
    }
}

调用 Endpoint API​

调用 Endpoint API 时，必须要使用一个有效的 Access Token 进行认证。如果是文件上传相关的 API，还需要附上用户针对文件 CID 生成的数字签名。比如，调用 pinFile 的 curl 命令如下：

curl -X POST "https://api-sh.decoo-cloud.cn/pinning/pinFile" \
  -H "UserAccessToken: <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@<YOUR_FILE_PATH>" \
  -F 'decooMetadata="{\"name\": \"我的文件\"}"' \
  -F "cid=<YOUR_FILE_CID>" \
  -F "secret=<YOUR_DIGITAL_SIGNATURE>"

更多详细信息，可以参考相关 API 说明。

Client SDK​

如前所述，Baitech 提供了 JavaScript 版本的 Client SDK，封装了 Endpoint 连接、申请 Access Token、生成 数字签名 等功能。用户可以使用它很方便地调用 Endpoint API。

该 SDK 同时支持 NodeJS 和 Browser 环境。详细使用说明可参考 SDK 本身页面。