ArtistCommons API Version 1.0.3

仕様書/シーケンス図

2021-03-19

目次

対象範囲

用語の定義

ArtistCommonsサーバ

indexer, id converter, data provider の3種類のサーバを定義する。

1サーバで複数機能を兼ねてもよい。

ArtistCommonsを利用するシステム(アプリケーションサーバ等)を、applicationと記載する

indexer, id converter, data provider と、applicationの関係

ArtistCommonsサーバ

ArtistCommons API

API接続認証

以下をリクエストクエリに追加する。

?access_key={string}&sign={string}

access_key: サーバ管理者から払い出されたアクセスキー

sign: サーバ管理者から払い出されたシークレットキーでAPIリクエストを署名したもの

クライアント登録のシーケンス

クライアント登録

ID API

ある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変換

Data API

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

レスポンスフォーマット (各データタイプ固有の部分)

NowOnAir

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取得のシーケンス

DATA取得シーケンス

indexerによるキャッシュ

indexerキャッシュ

Index API

どんなデータが処理可能かのリストを返却する 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}"
  }
}

INDEX取得のシーケンス

INDEX取得シーケンス