ArtistCommons API Version 1.0.3
仕様書/シーケンス図
2021-03-19
データプロバイダ
設計の対象
ArtistCommons サーバ:
ArtistCommons API:
ID :
DATA :
API接続認証 :
indexer, id converter, data provider の3種類のサーバを定義する。
1サーバで複数機能を兼ねてもよい。
indexer
id converter
data provider
ArtistCommonsを利用するシステム(アプリケーションサーバ等)を、applicationと記載する
以下をリクエストクエリに追加する。
?access_key={string}&sign={string}
access_key: サーバ管理者から払い出されたアクセスキー
sign: サーバ管理者から払い出されたシークレットキーでAPIリクエストを署名したもの
クライアント手順
サーバ手順
operatorは管理画面等による人間の操作を表す。
clientはリクエスト元を、serverはリクエスト先を表す。
この図でのID登録は、ArtistCommons利用におけるclientとしてのID。(コンテンツのIDではない)
右下の記載の意味: このシーケンスが該当する組み合わせは
あるIDタイプのIDを別のIDタイプのIDに変換する
id converter, indexer が提供する
GET /api/v0/id/{data_type}/{id_type}/{id}
GET /api/v0/id/{data_type}/{id_type}/{id}/{to_id_type}
?provider={string}
ID検索
GET /api/v0/id/{data_type}/search
GET /api/v0/id/{data_type}/search/{to_id_type}
?name={string}&provider={string}
各検索条件クエリは省略可能
ステータスコード
成功時
{
"status": "succeeded",
"request": {
"uri": "{request_uri}"
},
"data": [
{
"indexer": "{indexer_url}",
"provider": "{provider_url}",
"published_at": "{published_datetime}",
"expired_at": "{expired_datetime}",
"body": {
"@context": "http://schema.org",
"@type": "Person",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{performer_name}"
}
}
]
}
失敗時
{
"status": "failed",
"request": {
"uri": "{request_uri}"
},
"error": {
"message": "{error_message}"
}
}
日時の書式はISO 8601
2018-06-28T10:32:21+09:00
あるID体系のIDまたはnameでリクエストすると、希望するID体系のIDがレスポンスされる。
シーケンス動作は、IDとDATAで同じ。
IDから詳細データを返却する data provider, indexer が提供する
GET /api/v0/data/{data_type}/{id_type}/{id}
?begun_at={datetime}&ended_at={datetime}&provider={string}
日時の書式はISO 8601をURLエンコードする
2018-06-28T10%3A32%3A21%2B09%3A00
ステータスコード
成功時 {content}には以下の項の情報が入る
{
"status": "succeeded",
"request": {
"uri": "{request_uri}"
},
"data": [
{
"indexer": "{indexer_url}",
"provider": "{provider_url}",
"published_at": "{published_datetime}",
"expired_at": "{expired_datetime}",
"body": "{content}"
}
]
}
失敗時
{
"status": "failed",
"request": {
"uri": "{request_uri}"
},
"error": {
"message": "{error_message}"
}
}
日時の書式はISO 8601
2018-06-28T10:32:21+09:00
Type: http://schema.org/PlayAction
{
"@context": "http://schema.org",
"@type": "PlayAction",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"hasPart": [
{
"@type": "PlayAction",
"object": {
"@type": "MusicRecording",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{song_name}",
"byArtist": {
"@type": "MusicGroup",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{artist_name}"
}
},
"startTime": "{start_datetime}",
"endTime": "{end_datetime}"
}
]
}
Type: http://schema.org/MusicRecording
{
"@context": "http://schema.org",
"@type": "MusicRecording",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{song_name}",
"byArtist": {
"@type": "MusicGroup",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{artist_name}",
},
"inAlbum": {
"@type": "MusicAlbum",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{album_name}"
},
"audio": {
"@type": "AudioObject",
"contentUrl": "{audio_url}"
},
"image": {
"@type": "ImageObject",
"contentUrl": "{image_url}"
},
"contributor": [
{
"@type": "Person",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{artist_name}",
"jobTitle": "{role}"
}
]
}
Type: AudioSequence "AudioSequence" は "http://schema.org/CreativeWork"のカスタム派生タイプ
{
"@type": "AudioSequence",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{audio_sequence_name}",
"description": "{audio_sequence_description}",
"hasPart": [
{
"@type": "AudioSequence",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{audio_sequence_name}",
"startDuration": "{start_duration}",
"endDuration": "{end_duration}"
}
]
}
Type: AudioRecording "AudioRecording" は "http://schema.org/CreativeWork"のカスタム派生タイプ
{
"@context": "http://schema.org",
"@type": "AudioObject",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{audio_name}",
"audio": {
"@type": "AudioObject",
"contentUrl": "{audio_url}"
},
"duration": "{audio_duration}",
"contributor": [
{
"@type": "Person",
"identifier": {
"@type": "PropertyValue",
"propertyID": "{id_type}",
"value": "{id}"
},
"name": "{performer_name}"
}
]
}
欲しいDATA(コンテンツ及びメタデータ)の、datatypeと、ID体系とIDのセットを指定してリクエストすると、希望するDATAがレスポンスされる。
シーケンス動作は、IDとDATAで同じ。
どんなデータが処理可能かのリストを返却する id converter, data provider, indexer が提供する
GET /api/v0/index
ステータスコード
成功時
{
"status": "succeeded",
"request": {
"uri": "{request_uri}"
},
"data": [
{
"indexer": "{indexer_url}",
"provider": "{provider_url}"
"provider_type": "{provider_type}",
"data_type": "{data_type}",
"id_type": "{id_type}",
"to_id_types": [
{id_type}
],
"search_keys": [
{search_key}
]
}
]
}
失敗時
{
"status": "failed",
"request": {
"uri": "{request_uri}"
},
"error": {
"message": "{error_message}"
}
}
IDやDATAについて、どのプロバイダがどのような検索に対応しているかを取得するシーケンス。
indexerは、IDプロバイダやDATAプロバイダに問い合わせて、どのような情報があるかを把握する他、連携する他のindexerに定期的に問い合わせを行い、結果を保持することにより、自分の配下のプロバイダに情報が無い場合に他のindexerへ問い合わせることを可能にする。