REST APIの概要

Omeka Sは、すべてのリソースに対してREST APIを提供しています。APIを通じて、アイテム、メディア、アイテムセット、サイト、ページなどのリソースを取得・作成・更新・削除できます。

APIのベースURLは以下の形式です。

https://your-domain/api/

APIへのアクセス制限

APIのアクセス制限について、筆者はOmeka SのAPIへのアクセス制限で詳しく解説しています。公開リソースの読み取り（GET）は認証なしで行えますが、リソースの作成（POST）、更新（PUT/PATCH）、削除（DELETE）には認証が必要です。

認証には、APIキーを使用します。管理画面の「Users」から該当ユーザの編集画面を開き、「API keys」タブでキーを生成します。

https://your-domain/api/items?key_identity={identity}&key_credential={credential}

:::message alert APIキーはURLに含まれるため、HTTPSを使用しないとキーが平文で送信されてしまいます。本番環境では必ずHTTPSを使用してください。 :::

レスポンス形式

APIのレスポンスはJSON-LD形式で返されます。これは、通常のJSONとして処理できると同時に、Linked Dataとしての意味的な構造も保持しています。

アイテムの取得と検索

アイテム一覧の取得

curl "https://your-domain/api/items"

ページネーション

# 1ページ目、50件ずつ
curl "https://your-domain/api/items?per_page=50&page=1"

# 2ページ目
curl "https://your-domain/api/items?per_page=50&page=2"

レスポンスヘッダに総件数が含まれます。

Omeka-S-Total-Results:328

検索・フィルタリング

# アイテムセットで絞り込み
curl "https://your-domain/api/items?item_set_id=1"

# キーワード検索
curl "https://your-domain/api/items?search=源氏物語"

# プロパティ値で検索（部分一致）
curl "https://your-domain/api/items?property[0][property]=1&property[0][type]=in&property[0][text]=源氏"

# ソート
curl "https://your-domain/api/items?sort_by=dcterms:title&sort_order=asc"

アイテムの作成

APIキーを使って認証し、POSTリクエストでアイテムを作成します。

curl -X POST "https://your-domain/api/items?key_identity=xxx&key_credential=yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "dcterms:title": [
      {
        "type": "literal",
        "@value": "東京名所写真帖",
        "@language": "ja"
      }
    ],
    "dcterms:creator": [
      {
        "type": "literal",
        "@value": "小川一眞",
        "@language": "ja"
      }
    ],
    "o:is_public": true
  }'

PythonによるAPI活用

筆者は、Omeka SのREST APIをPythonから操作するためのパッケージを開発しました。Omeka SのREST APIとやりとりするためのPythonパッケージで紹介しています。

Pythonを使ったメディアのアップロード

Pythonスクリプトを使って画像をアップロードする方法についてはPythonを使ってOmeka Sにメディアをアップロードする方法で解説しています。

アイテム一覧のCSVエクスポート

import requests
import csv

BASE_URL = "https://your-domain/api"

def fetch_all_items():
    """全アイテムを取得"""
    items = []
    page = 1
    while True:
        response = requests.get(
            f"{BASE_URL}/items",
            params={"per_page": 50, "page": page}
        )
        data = response.json()
        if not data:
            break
        items.extend(data)
        page += 1
    return items

def get_value(item, property_name):
    """プロパティの最初の値を取得"""
    values = item.get(property_name, [])
    if values:
        v = values[0]
        return v.get("@value", v.get("o:label", v.get("@id", "")))
    return ""

items = fetch_all_items()
with open("items_export.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["ID", "Title", "Creator", "Date"])
    for item in items:
        writer.writerow([
            item["o:id"],
            get_value(item, "dcterms:title"),
            get_value(item, "dcterms:creator"),
            get_value(item, "dcterms:date"),
        ])

print(f"Exported {len(items)} items")

語彙のプロパティ一覧取得

特定の語彙に属するプロパティの一覧をAPIから取得する方法についてはOmeka Sの特定のvocabularyのプロパティ一覧を取得するで解説しています。

データのダウンロード

筆者は、Omeka Sのデータを一括でダウンロードするプログラムを作成しています。Omeka Sのデータをダウンロードするプログラムを作成しました。で紹介しています。Google Colabで実行できるため、手軽に利用できます。

Omeka ClassicのデータダウンロードについてもOmeka Classicのデータをダウンロードするプログラムを作成しました。で紹介しています。

MCPサーバーを使った連携

最新のアプローチとして、MCPサーバーを使ってClaudeなどのAIアシスタントからOmeka SのAPIを操作する方法があります。MCPサーバーを使って、Omeka Sにリソース（アイテムと画像）を登録するで紹介しています。

Omeka ClassicをHeadless CMSとして使用

Omeka ClassicのAPIを使って、HeadlessなCMSとして利用する方法についてOmeka ClassicをHeadless CMSとして使用してみる。で解説しています。Nuxt.js/Vue.jsを使ったフロントエンド構築の例を紹介しています。この考え方はOmeka Sにも応用可能です。

外部システム連携

OAI-PMH連携

OAI-PMHプロトコルを使ったメタデータハーベスティングについては、前章のモジュール紹介で触れました。Pythonを使ったOAI-PMHリポジトリからのデータ取得についてはOAI-PMHリポジトリからPythonでレコードを全件取得するで解説しています。

静的サイトジェネレータとの連携

APIからデータを取得し、Next.jsやHugoなどの静的サイトジェネレータでカスタムサイトを構築できます。Omeka Sをヘッドレスなデータ管理基盤として利用するパターンです。

// Next.jsでのデータ取得例
export async function getStaticProps() {
  const res = await fetch('https://your-domain/api/items?per_page=100');
  const items = await res.json();

  return {
    props: { items },
    revalidate: 3600,
  };
}

エクスポートリンクの設置

アイテムの詳細画面に各種エクスポートリンクを設置するモジュールについて、【Omeka S モジュール開発】アイテムの詳細画面に各種エクスポートリンクを設置するモジュールを開発しました。で紹介しています。JSON-LD、Turtle、RDF/XMLなどの形式でデータをダウンロードできるリンクをサイトに追加できます。

まとめ

本章では、Omeka SのREST APIの概要、アイテムのCRUD操作、検索・フィルタリング、PythonによるAPI活用、外部システム連携の事例について解説しました。

REST APIは、Omeka Sのデータを外部から活用するための強力な手段です。Bulk Importでカバーできない高度なデータ操作や、他のシステムとの連携において、APIの活用は不可欠となるでしょう。

次章では、テーマのカスタマイズ方法について解説します。

関連記事