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/{account}/{db}/api/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/$ACC/nishikie/api/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/$ACC/nishikie/api/search?q=国芳&facet=placeName"代表的なエンドポイント
| メソッド | パス | スコープ | 用途 |
|---|---|---|---|
| GET | /api/accounts | (公開 / 任意) | プラットフォーム上のライブラリ一覧。各 db は service(dl/text/records)を返すので /{account}/{slug} を組める。?scope=mine(要認証: セッション or API キー)で自分の非公開 db も含む一覧、?scope=all(管理者のみ)で全 db |
| PATCH | /{account}/{db}/api/database | write | サイト設定の更新。{settings:{service:'text'}} で配信アプリ(dl/text/records)を切替(公開 URL が変わり旧パスは 307 転送)。card(サイト一覧カード) / provider(提供機関名) / ogImage も API キーだけで設定できる。他の表示系キーは Swagger 参照 |
| GET | /{account}/{db}/api/resources | read | 一覧(type / parent / page[...]) |
| POST | /{account}/{db}/api/resources | write | 作成 |
| GET | /{account}/{db}/api/resources/{id} | read | 取得(slug または uuid)。?format=jsonld 等で LOD エクスポート(下記) |
| PATCH | /{account}/{db}/api/resources/{id} | write | 部分更新 |
| DELETE | /{account}/{db}/api/resources/{id} | write | 削除 |
| GET | /{account}/{db}/api/search | (公開) | 検索・ファセット |
| GET/POST | /{account}/{db}/api/oai | (公開) | OAI-PMH 2.0 ハーベスト(下記) |
| POST | /{account}/{db}/api/import | write | CSV 一括登録(Omeka CSVImport 互換) |
| POST | /{account}/{db}/api/uploads | write | バイナリの presigned S3 PUT URL 発行。derivative:'ptif' で IIIF 画像パイプライン(下記) |
| POST | /api/{account}/uploads/{asset}/finalize | write | tiled アップロードの変換キュー投入(source の PUT 後に叩く) |
| GET | /api/{account}/uploads/{asset} | read | 変換状態ポーリング({status, is_public, width, height, iiif}) |
| PATCH | /api/{account}/uploads/{asset} | write | asset 更新(ワーカーの ready 化 / 画像単位の is_public 切替) |
| GET | /api/{account}/iiif-img/3/{asset}/info.json | (公開 asset) | IIIF Image API(Cantaloupe プロキシ。ベース URI は info.json へ 303) |
| GET | /api/{account}/usage | read | 使用量 |
IIIF 画像パイプライン: POST /uploads に derivative:'ptif' を付けると、presign → PUT → finalize → バックグラウンドで libvips がピラミッド TIFF に変換 → GET /uploads/{asset} が ready になったら IIIF Image API で配信、という流れになります。画像(asset)はアカウント所有で、 公開/非公開は画像単位(is_public)です。詳細は Swagger UI の uploads / tenant-iiif タグを参照。
LOD エクスポート(JSON-LD / RiC-O / Turtle)
すべてのリソースは GET /resources/{id} の ?format= で LOD (Linked Open Data) として 取得できます。公開リソースは鍵不要です。
| format | 内容 |
|---|---|
jsonld | schema.org ベースの JSON-LD(ジャパンサーチ利活用スキーマ系)。どんな資料でも使える既定プロファイル |
rico | RiC-O(Records in Contexts)JSON-LD。アーカイブズ記述の階層(フォンド/シリーズ/簿冊)・担体(Instantiation)を表現 |
ttl / rico-ttl | 上記各プロファイルの Turtle 直列化(RDF ツール向け) |
# schema.org JSON-LD(既定プロファイル)
curl "https://archivebase.ldas.jp/demo/library/api/resources/doc-1?format=jsonld"
# RiC-O の Turtle
curl "https://archivebase.ldas.jp/demo/library/api/resources/doc-1?format=rico-ttl"@idはデータ URI/{account}/{db}/data/{id}(モノの一意 URI)です。プログラムから 取得すると JSON-LD/Turtle が返り、ブラウザで開くと 303 でアイテム詳細ページ (/resource/{id})に転送されます — Wikidata やジャパンサーチと同じ流儀です。- メタデータのキーは RDF プロパティへ写像されます:
dcterms:dateのような CURIE キーは そのまま、licenseのような正準キーは対応プロパティ(schema:license等)へ。写像できない 自由キーはschema:descriptionに「キー: 値」として集約され、情報は失われません。 - 親子関係は
schema:isPartOf/schema:hasPart(RiC-O ではrico:isOrWasIncludedIn/rico:hasInstantiationなど)で、公開範囲内のリソースだけがリンクされます。 - アイテム詳細ページの共有レールにも「LOD (JSON-LD)」リンクが出ます(記述階層を設定した サイトでは「RiC-O」も)。
SPARQL エンドポイント
サイト設定 rdf を有効にしたサイトは、全公開リソースの RDF グラフ(schema.org + RiC-O)を トリプルストアに持ち、読み取り専用 SPARQL エンドポイントを公開します。鍵は不要です。
curl -G "https://archivebase.ldas.jp/api/demo/dl/library/sparql" --data-urlencode 'query=
PREFIX schema: <https://schema.org/>
SELECT ?s ?name WHERE { ?s schema:name ?name } LIMIT 10'- 既定グラフはそのサイトのグラフです。
GRAPH ?g { … }で他の公開サイトも横断できます (ストアには公開リソースしか入っていません)。 - 結果形式は
Acceptヘッダで選べます(JSON / XML / CSV / Turtle)。 - グラフの一括(再)構築はサイト管理者が
POST …/rdf-indexで行います。
OAI-PMH(一括ハーベスト)
公開サイトは OAI-PMH 2.0 の プロバイダとして振る舞います。ジャパンサーチのようなアグリゲータに、サイトの メタデータを丸ごと収集させるための標準的な出口です。
# リポジトリの情報
curl "https://archivebase.ldas.jp/{account}/{db}/api/oai?verb=Identify"
# Dublin Core で全件
curl "https://archivebase.ldas.jp/{account}/{db}/api/oai?verb=ListRecords&metadataPrefix=oai_dc"
# ジャパンサーチ利活用スキーマ(RDF/XML)で全件
curl "https://archivebase.ldas.jp/{account}/{db}/api/oai?verb=ListRecords&metadataPrefix=jps"- 動詞は 6 つすべて対応(
Identify/ListMetadataFormats/ListSets/ListIdentifiers/ListRecords/GetRecord) metadataPrefixはoai_dc(Dublin Core)とjps(ジャパンサーチ利活用スキーマ)setはリソースの種別(item/collection…)。ListSetsで列挙できますfrom/untilで更新日による差分収集ができます- 続きは
resumptionTokenで取ります。取得件数に上限はありません - 出るのは公開サイトの公開リソースだけです。非公開サイトは 404 になります
プロトコルのエラーは HTTP 200 で返ります
OAI-PMH の規約により、引数の誤りなどは HTTP ステータスではなく本文の <error code="..."> で表されます。HTTP 200 だけを見て成功と判断しないでください。
典拠(entities)とクエリ拡張
アカウント横断の典拠レコード(人名・地名・組織など)を登録できます。各典拠は entityType + prefLabel(多言語)+ altLabels(異表記・音写)+ sameAs (Wikidata/GeoNames などの URI)を持ちます。読み取りは鍵不要です。
# 典拠を作る(オーナーのキー)
curl -s -X POST "$BASE/api/$ACC/entities" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"slug":"nagasaki","entityType":"place","prefLabel":{"ja":"長崎","en":"Nagasaki"},"altLabels":["Nangazackische"],"sameAs":["http://www.wikidata.org/entity/Q38620"],"coordinates":{"lat":32.7448,"lon":129.8737}}'
# 典拠の LOD
curl -s "$BASE/api/$ACC/entities/nagasaki?format=jsonld"クエリ拡張: 検索に &expand=entities を付けると、検索語が典拠のラベルに一致した とき altLabels 込みの全ラベルで OR 検索します。たとえば「長崎」で検索すると、 オランダ語綴り Nangazackische しか含まない翻刻本文もヒットします(応答の expanded に採用ラベルが載ります)。
curl -s "$BASE/$ACC/voc/api/search?q=長崎&expand=entities"また、リソースの LOD(?format=jsonld や /data/{id})では、メタデータ中の言及が典拠の ラベルに一致すると schema:about で典拠へ自動リンクされます。
典拠はダッシュボードの「典拠」ページでも GUI で管理できます(一覧・作成・編集・削除、place 典拠の地図表示)。
検索クエリ(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/{account}/{db}/api/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": "..." } で返ります。
独自ドメイン
公開サイトに独自ホスト名を割り当てられます(Vercel 風。内部でテナントへ rewrite され、URL バーはホスト名のまま)。2 種類:*.ldas.jp のサブドメイン(即配信)と、顧客所有の外部ドメイン(Cloudflare for SaaS。返却される CNAME/TXT を設定 → {host,verify:true} で検証 → 配信)。いずれも公開 DB 限定・CF エッジ経由なので WAF が効く。管理は Firebase セッションの GET/POST/DELETE /api/me/domains(またはダッシュボードの「サイト詳細」→「独自ドメイン」)。詳細は 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 等)対応の有無を追記予定。
ResourceSync (同期)
公開サイトの内容を外部システムへ同期させたい場合、ResourceSync (ANSI/NISO Z39.99-2017) を利用できます。Sitemap プロトコルの拡張で、認証は不要です。
入口は https://archivebase.ldas.jp/.well-known/resourcesync(独自ドメインなら https://<そのホスト>/.well-known/resourcesync)。ここから各サイトの Capability List を辿れます。
| パス | 内容 |
|---|---|
/{account}/{db}/api/resourcesync/capabilitylist.xml | そのサイトが提供する文書の一覧 |
/{account}/{db}/api/resourcesync/resourcelist.xml | 現在の全公開リソース(1 万件ごとに ?p=N へ分割) |
/{account}/{db}/api/resourcesync/changelist.xml | 変更一覧。?from=2026-01-01T00:00:00Z で期間を絞れます |
各エントリの <loc> は機械可読な表現(LOD のデータ URI /{account}/{db}/data/{id}。既定で schema.org JSON-LD)を指し、人間向けの詳細ページは <rs:ln rel="alternate"> で併記されます。変更種別は created / updated のみで、削除は通知されません。Elasticsearch 連携サイト・横断検索サイトは更新時刻を持たないため対応していません(404)。