API を使う

すべてのエンドポイントは Swagger UI で一覧・試行できます。このページはその歩き方をまとめたものです。網羅的なリファレンスは Swagger UI と docs/API.md を参照してください。

認証

API キー(プログラム用)

書き込み系(リソースの作成・更新など)と非公開データの読み取りには API キーが必要です。キーはアカウントに紐づき、read / write のスコープを持ちます。

Authorization: Bearer <public_id>.<secret>

発行方法:

ダッシュボード /dashboard/keys(Google ログイン)→「新しいキーを発行」
POST /api/me/keys(Firebase ID トークン)

秘密値は一度だけ

キーの秘密値(.secret)は発行時に一度しか表示されません(サーバには sha256 ハッシュのみ保存)。安全な場所(1Password 等)に保管してください。漏れた場合は失効させて再発行します。

公開データの読み取りは鍵不要

公開(is_public)なリソースの一覧・検索・取得は認証なしで利用できます。

# サイト内検索 (公開アイテムのみが返る)
curl 'https://archivebase.ldas.jp/api/{account}/dl/{db}/search?q=検索語'

クイックスタート(curl)

KEY="ak_xxxxxxxx.yyyyyyyyyyyy"          # ダッシュボードで発行
BASE="https://archivebase.ldas.jp"
ACC="your-account"

データベース(ライブラリ)を作る

curl -s -X POST "$BASE/api/$ACC/databases" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"slug":"nishikie","title":"錦絵コレクション"}'

リソース(アイテム)を作る

curl -s -X POST "$BASE/api/$ACC/dl/nishikie/resources" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
        "slug":"0380-17-1",
        "type":"item",
        "title":"道化武者づくし",
        "metadata":{"dcterms:creator":"歌川国芳","year":"1858"}
      }'

検索する(鍵不要)

curl -s "$BASE/api/$ACC/dl/nishikie/search?q=国芳&facet=placeName"

代表的なエンドポイント

メソッド	パス	スコープ	用途
GET	`/api/{account}/dl/{db}/resources`	read	一覧(`type` / `parent` / `page[...]`)
POST	`/api/{account}/dl/{db}/resources`	write	作成
GET	`/api/{account}/dl/{db}/resources/{id}`	read	取得(slug または uuid)
PATCH	`/api/{account}/dl/{db}/resources/{id}`	write	部分更新
DELETE	`/api/{account}/dl/{db}/resources/{id}`	write	削除
GET	`/api/{account}/dl/{db}/search`	(公開)	検索・ファセット
POST	`/api/{account}/dl/{db}/import`	write	CSV 一括登録(Omeka CSVImport 互換)
POST	`/api/{account}/dl/{db}/uploads`	write	バイナリの presigned S3 PUT URL 発行
GET	`/api/{account}/usage`	read	使用量

検索クエリ(JSON:API スタイル)

/search は次のパラメータを取ります。

q — 検索語(websearch 構文)
facet=<キー> — 集計する metadata キー(複数指定可)
filter[<キー>]=<値> — metadata による絞り込み(同じキーの繰り返しで OR)
page[number] + page[size](または page[limit] + page[offset])— ページング
sort=<キー> — 並び替え。- プレフィックスで降順(sort=-year)

curl 'https://archivebase.ldas.jp/api/{account}/dl/{db}/search?q=北斎&filter[persName]=葛飾北斎&page[size]=20&sort=-year'

旧パラメータは非推奨

limit / offset / dir / 裸の metadata パラメータは非推奨で、Swagger 上でも deprecated 宣言済みです。新規実装は page[...] / filter[...] / sort=-<キー> を使ってください。

アクセス制御とエラー

非公開のデータベース・アイテムは、権限のないリクエストに 404 を返します(存在自体を秘匿)
他アカウントのリソースへの書き込みは 403(スコープ不足)
認証が必要なエンドポイントへの匿名アクセスは 401
slug の重複は 409、クォータ超過は 402、単体アップロードのサイズ超過は 413

エラーは JSON { "error": "..." } で返ります。

独自ドメイン

公開サイトに xxxx.ldas.jp の独自ホスト名を割り当てられます(Vercel 風。内部でテナントへ rewrite され、URL バーはホスト名のまま)。管理は Firebase セッションの GET/POST/DELETE /api/me/domains(またはダッシュボードの「サイト詳細」→「独自ドメイン」)。当面は *.ldas.jp の単一ラベルのみ・公開 DB 限定。詳細は Swagger と公開ガイドを参照。

一括投入

CSV(Omeka CSVImport 互換) — ダッシュボードの「サイト詳細」または POST /dl/{db}/import
dcb 形式 — collection.csv / item.csv / media.csv / annotation.csv を投入するインポータ(npm run import:dcb)

執筆中

API キーのスコープ設計の詳細、レート制限、Webhook/収穫(OAI-PMH 等)対応の有無を追記予定。

API を使う ​

認証 ​

API キー(プログラム用) ​

公開データの読み取りは鍵不要 ​

クイックスタート(curl) ​

代表的なエンドポイント ​

検索クエリ(JSON:API スタイル) ​

アクセス制御とエラー ​

独自ドメイン ​

一括投入 ​