REST API

REST API は PHP API の上に構築されたサービス層であり、PHP で利用可能な操作のほとんど（ただし全てではない）が REST を使用しても利用できます。

エンドポイント

API は Omeka S インストールのルートの下にある/apiに位置しています。

フォーマット

HTTP レスポンスは、JSON を使用して Linked Data を転送する方法であるJSON-LDでフォーマットされます。

リクエストのペイロードも JSON-LD であるべきですが、Omeka S は時折クライアントに特定の構造をフォローすることを要求することがあります。これは同じデータが代替の有効な JSON-LD 構造によって表現されうるにも関わらずです。ペイロードが含まれるリクエストの Content-Type はapplication/jsonでなければなりません（マルチパートリクエストを送信する場合はmultipart/form-data）。フォーマット指定子（例：application/ld+json）を含むことも許容されます。

認証

API は公開リソースへの匿名アクセスを許可しています（つまり、非プライベートデータの読み取り）。ログインユーザのみがアクセス可能なアクションを実行したりデータを閲覧するためには、リクエストの認証が必要です。

認証には、すべてのリクエストに 2 つの追加の GET パラメータを含める必要があります： key_identityとkey_credential。Omeka S ユーザは、自分のユーザ編集ページの "API キー"タブで API キーを生成できます。

API 操作

検索

GET /api/:api_resource

リソースを検索またはリストする場合、オプションで条件を指定できます。フィルタリング、制限、または検索結果を変更するためのパラメータはクエリ文字列の GET パラメータとして渡されます。追加のページへのリンクはLinkヘッダで与えられます。rel="next"のリンクがシーケンスの次のページです。適切な場合には、rel値がprev、first、last のリンクも提供されます。

Omeka S 3.0.0 から、検索レスポンスには全ページにわたる結果の合計数を示すOmeka-S-Total-Resultsヘッダが含まれます。

読み取り

GET /api/:api_resource/:id

既知の ID で単一のリソースを取得します。idパラメータは必須です。

作成

POST /api/:api_resource

リソースを作成します。JSON ペイロードが必要です。

ファイルのアップロード

ファイルのアップロードを伴う作成操作については、マルチパートリクエスト（Content-Type multipart/form-data）がサポートされています。マルチパートリクエストでは、通常の JSON リクエストボディを dataという名前の「フィールド」として指定する必要があります。asset API リソースは関連するファイルがfileと名付けられることを期待しています。メディアをアップロードする場合（mediaの作成操作やitemの作成または更新操作の一部として）、ファイルは「配列」として名付けられることが期待されています（例：file[0]、file[1]）。メディアやアイテムの JSON ボディは、この配列のインデックスをfile_indexキーで指定します。

"o:ingester": "upload",
"file_index": 0,

...

更新

PUT /api/:api_resource/:id

リソースを更新します。id URL パラメータは必須です。JSON ペイロードが必要です。ペイロードは、指定した ID の既存のリソースを完全に更新・置き換えます。したがって、変更を行う場合は、通常はリソースの現在の状態を読み取り、返された JSON を変更して、それを更新として提出することが賢明です。代替として「部分的に」更新を実行することもできます。

部分的更新（パッチ）

PATCH /api/:api_resource/:id

指定されていないキーのデータを保持しながらリソースを更新します。id URL パラメータは必須です。JSON ペイロードが必要です。アイテム、アイテムセット、メディアの「値」としての RDF プロパティの任意の値を指定すると、一般的にその値が「更新」されるとみなされます（つまり、RDF プロパティの値が 1 つでも指定されると、渡されなかった他の全ての値が削除されるということです）。つまり、値はパッチ目的で一つの大きな「キー」であるかのように扱われます。

削除

DELETE /api/:api_resource/:id

リソースを削除します。id URL パラメータは必須です。