API key

你的应用通过 API key 访问数据库:一个密钥和一个 secret,通过两个请求头发送。数据库、API key 和所有者都在 InceptionDB 控制台 中管理,使用你的 hola.cloud 账户登录。

创建数据库

在控制台中打开数据库选择器,选择 New database。大约一秒即可就绪。它的 ID 显示在概览页面上:这就是 INCEPTIONDB_DATABASE 的值。

创建 API key

  1. 选择数据库并打开 API keys & settings。
  2. 点击 New API key,以将使用它的应用命名,例如 backend-production。
  3. 复制 secret。它只显示一次:InceptionDB 只保存其哈希值。

控制台会给出可以直接使用的凭据,例如作为环境变量:

1export INCEPTIONDB_DATABASE="your-database-id"
2export INCEPTIONDB_API_KEY="your-api-key"
3export INCEPTIONDB_API_SECRET="your-api-secret"

一个 API key 可以访问其数据库中的所有集合,且只能访问这个数据库。

使用

在每个请求的 Api-Key 和 Api-Secret 请求头中发送密钥和 secret:

curl "https://inceptiondb.hola.cloud/v1/databases/$INCEPTIONDB_DATABASE/collections" \
  -H "Api-Key: $INCEPTIONDB_API_KEY" \
  -H "Api-Secret: $INCEPTIONDB_API_SECRET"
GET /v1/databases/$INCEPTIONDB_DATABASE/collections HTTP/1.1
Host: inceptiondb.hola.cloud
Api-Key: $INCEPTIONDB_API_KEY
Api-Secret: $INCEPTIONDB_API_SECRET
// Go 1.21+, standard library only. Save as main.go and run: go run main.go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://inceptiondb.hola.cloud/v1/databases/" + os.Getenv("INCEPTIONDB_DATABASE") + "/collections", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Api-Key", os.Getenv("INCEPTIONDB_API_KEY"))
	req.Header.Set("Api-Secret", os.Getenv("INCEPTIONDB_API_SECRET"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	responseBody, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(resp.Status)
	fmt.Println(string(responseBody))
}
<?php
// PHP 8+ with the curl extension. Save as example.php and run: php example.php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://inceptiondb.hola.cloud/v1/databases/' . getenv('INCEPTIONDB_DATABASE') . '/collections',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Api-Key: ' . getenv('INCEPTIONDB_API_KEY'),
        'Api-Secret: ' . getenv('INCEPTIONDB_API_SECRET'),
    ],
]);

$response = curl_exec($ch);
if ($response === false) {
    throw new Exception(curl_error($ch));
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), "\n", $response, "\n";
curl_close($ch);
# Python 3.8+. Install: pip install requests. Save as example.py and run: python example.py
import os
import requests

headers = {
    "Api-Key": os.environ["INCEPTIONDB_API_KEY"],
    "Api-Secret": os.environ["INCEPTIONDB_API_SECRET"],
}

response = requests.request(
    "GET",
    "https://inceptiondb.hola.cloud/v1/databases/" + os.environ["INCEPTIONDB_DATABASE"] + "/collections",
    headers=headers
)

print(response.status_code)
print(response.text)
// Node.js 18+. Save as example.mjs and run: node example.mjs
const response = await fetch("https://inceptiondb.hola.cloud/v1/databases/" + process.env.INCEPTIONDB_DATABASE + "/collections", {
  method: "GET",
  headers: {
    "Api-Key": process.env.INCEPTIONDB_API_KEY,
    "Api-Secret": process.env.INCEPTIONDB_API_SECRET
  }
});

console.log(response.status);
console.log(await response.text());
// Java 17+, standard library only. Save as Main.java and run: java Main.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        var request = HttpRequest.newBuilder()
            .uri(URI.create("https://inceptiondb.hola.cloud/v1/databases/" + System.getenv("INCEPTIONDB_DATABASE") + "/collections"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .header("Api-Key", System.getenv("INCEPTIONDB_API_KEY"))
            .header("Api-Secret", System.getenv("INCEPTIONDB_API_SECRET"))
            .build();

        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
1[{"defaults":{"id":"uuid()"},"indexes":0,"name":"customers","total":2}]

密钥或 secret 错误时返回 403 Forbidden。

保证安全

  • InceptionDB 是服务器到服务器的 API。不要在浏览器或移动应用中运行的代码里调用它:任何人都能在那里读到 secret。如果网页需要数据,让它调用你自己的后端,由后端保存 secret 并调用 InceptionDB。
  • 把 secret 保存在服务器上,放在环境变量或密钥管理器中。不要放在代码、代码仓库、网页或移动应用中:任何看到它的人都能读取和修改你的数据。
  • 每个应用或环境使用一个 API key。这样撤销其中一个不会影响其他的。
  • 如果 secret 泄露,创建一个新密钥并部署,然后在 API keys & settings 中撤销旧密钥。被撤销的密钥立即失效。

所有者

所有者是通过控制台管理数据库的 hola.cloud 用户:管理其集合、API key 和其他所有者。在 API keys & settings 中添加或移除。数据库始终至少保留一个所有者,且你不能移除自己。

账户操作:仅限控制台

创建、重命名和删除数据库,以及管理 API key 和所有者,都在控制台中完成。API 参考 列出了这些端点,用于说明控制台做了什么,但它们不用于自动化:

  • Api-Key 和 Api-Secret 对它们无效。API key 只能用于其数据库中的集合。
  • 它们需要已登录控制台的用户会话,在控制台之外没有受支持的获取方式。

查看控制台操作的代码

控制台中的每个操作都是一个 HTTP 请求,控制台会显示如何在你的代码中发出它。点击侧边菜单底部带有 { } 图标的 API calls。它会列出最近的请求;选择其中一个,即可看到 curl、Go、Python 等语言的版本,可直接复制。每个新请求还会在控制台右边缘的窄栏中显示为一个彩色圆点;点击圆点会打开同样的视图。

评论

发表评论