オンセンAPIとは
ver.1.02
オンセンAPIとは、OAuth2.0を使ってTRPGオンラインセッションSNSの情報の取得や作成・編集などの機能を提供するAPIサービスです。
オンセンAPIの利用準備
はじめに
オンセンAPIを使用するには、オンセンAPIのクライアントID（client_id）とクライアントシークレット（client_secret）が必要となります。以下の手順にしたがって取得してください。
- trpg_session@yahoo.co.jp 宛にオンセンAPIの利用申請をお願いします。申請には以下の内容を明記してください。
- 名前
- 連絡先
- 利用目的
- サイト名
- サイトURL
- 利用申請後、当サイトで審査を行います。
- 審査後、クライアントIDとクライアントシークレットが連絡先に届きます。
オンセンAPIが使用されるまでのフロー
流れは次のとおりです。
- ユーザがアプリケーションによってAPIサーバへとリダイレクトされます。（ステップ１）
- リダイレクト先でAPIサーバが要求データに対するアクセスを認可するようユーザを促します。
- ユーザはアクセスを認可するとアプリケーションにリダイレクトで戻されます。
このときのURLは認可コードが付加します。（ステップ２） - アプリケーションは認可コードを使いAPIサーバへアクセストークンを要求します。（ステップ３）
- APIサーバはアプリケーションにアクセストークンを返します。（ステップ４）
- アプリケーションはアクセストークンを使いAPI処理要求を行います。（ステップ５）
- APIサーバはAPI処理要求の処理結果を返します。（ステップ５）
ステップ１：認可コード要求
認可URLにアクセスし、認可コード要求を開始します。
要求にはクエリパラメータをいくつか追加する必要があります。
認可URL
GET/POST https://trpgsession.click/api/oauth.php
Content-Type
application/x-www-form-urlencoded
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| client_id | string |
[必須]
クライアントID。アプリケーションを登録した際に割り当てられた値。
|
| redirect_uri | string |
[必須]
リダイレクトURI。アプリケーションへのアクセス認可が終わった後に
ユーザがリダイレクトで戻される場所。
|
| response_type | string |
[必須]
レスポンスの種類。 code という値を指定します。これはユーザが認可リクエストを承認した後、
認可コードをアプリケーションに返すことを示します。
|
| state | string |
[必須]
アプリケーションに対するCSRF攻撃を防ぐためにクライアントアプリケーションで使用する一意の値。
|
ステップ２：認可コード返却
承認プロセス中にエラーがなく、且つユーザがアクセスを承認した場合、
APIサーバはユーザをredirect_uriで指定されたアプリケーションのURLにリダイレクトします。
アプリケーションにリダイレクトで戻ってくるときAPIサーバは2つのGETクエリパラメータが付加します。
Content-Type
text/html
返却されたパラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| code | string | 認可コード。ユーザがアクセス要求を承認したことを示します。 |
| state | string |
最初にリクエストを送ったときに渡したstateパラメータの値。 この値をステップ1で生成した値と比較し一致しなければ、 悪意あるユーザによってアプリケーションにCSRF攻撃がしかけられた可能性があります。 したがって、この場合はOAuthフローを中断すべきです。 |
ステップ３：アクセストークン要求
アクセストークン発行URLにアクセスし、アクセストークン要求を開始します。
要求にはAuthorizationヘッダによるHTTP Basic認証（client_idをユーザ名、client_secretをパスワードに指定）で指定し、且つ以下のクエリパラメータを追加する必要があります。
アクセストークン発行URL
POST https://trpgsession.click/api/access_token.php
Content-Type
application/json
Authorizationヘッダサンプル
Authorization:Basic a1b2C3d4E5A6B7C8D9e0a1b2C3d4E5A6B7C8D9e0a1b2C3d4E5
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| code | string |
[必須]
アプリケーションに渡された認可コード。
|
| grant_type | string |
[必須]
グラントタイプ。 authorization_code という値を指定します。
これは認可コードをアクセストークンに交換することを示します。
|
ステップ４：アクセストークン返却
リクエストの認証が問題なく終わり、且つパラメータが適正であれば、APIサーバはアクセストークンを生成し、JSON形式で返します。
Content-Type
application/json
次にJSON形式でエンコードされたレスポンスの例を示します。
{
"access_token":"1234567890abcd",
"token_type":"Bearer"
}
返却されたJSON形式パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| access_token | string | APIリクエストを認可するときに使用するトークン。 |
| token_type | string | 発行されたアクセストークンの種類。 |
ステップ５：APIを呼び出す
全てのAPIは各APIごとのエンドポイントにステップ４で取得したアクセストークンをHTTPのAuthorizationヘッダと必要なクエリパラメータを付与して使用します。
Content-Type
application/json
Authorizationヘッダサンプル
Authorization:Bearer 1234567890abcd
全API共通の返却JSONパラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| error | integer |
[エラーが発生した場合のみ]
エラーコード
|
| error_description | string |
[エラーが発生した場合のみ]
エラー内容の説明
|
各種APIの説明
キャラクターリストの要求
キャラクターの一覧データをJSON形式で返します。
エンドポイントURL
GET/POST https://trpgsession.click/api/getcharlist.php
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| なし | ||
返却されたJSONの例を示します。
{
"charlist":[
{
"id":"1495531474450abc1",
"name":"ドワーフの戦士",
"game_type":"ソード・ワールド2.0",
"update_time":"1495533102",
"designated":"0"
},
{
"id":"1495531458256abc1",
"name":"エルフの神官",
"game_type":"ソード・ワールド2.0",
"update_time":"1495531548",
"designated":"1"
}
]
}
返却されたJSON形式パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| charlist | array | キャラクター配列 |
| id | string | キャラクターID |
| name | string | キャラクター名 |
| game_type | string | TRPGシステム名 |
| update_time | integer | 最終更新日時（UNIXTIME） |
| designated | integer |
0=共有キャラクターシート 1=専用キャラクターシート |
キャラクター情報の要求
指定したキャラクターデータをJSON形式で返します。
エンドポイントURL
POST https://trpgsession.click/api/getcharinfo.php
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| id | string |
[必須]
キャラクターID
|
返却されたJSONの例を示します。
{
"id":"148690231944abc1",
"name":"鈴木太郎",
"game_type":"ソード・ワールド2.0",
"update_time":"1608886108",
"image":"p/abc1/i/chara149290612416",
"hp":"21",
"mhp":"21",
"mp":"14",
"mmp":"14",
"condition":"加護 +1hp/時間",
"detail_a":"【種族】 人間 【性別】 女 ～以下、略",
"detail_b":"【魔物知識】 0 【先制力】 0 ～以下、略",
"detail_c":"【生い立ちなど】 狩りを ～以下、略",
"macro":"まもちき|2d+#魔物知識^めいはん|2d+器用度ボーナス+#命中",
"tag":"器用度ボーナス|2^筋力ボーナス|2^生命力ボーナス",
"designated":"0",
"display_detailc":"0",
"display_macro":"0",
"display_tag":"1",
"outer_url":"",
}
返却されたJSON形式パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| id | string | キャラクターID |
| name | string | キャラクター名 |
| game_type | string | TRPGシステム名 |
| update_time | integer | 最終更新日時（UNIXTIME） |
| image | string |
キャラクター画像・相対URL https://trpgsession.click/ を前に加えることで画像URLになります。 |
| hp | string | 現在HP |
| mhp | string | 最大HP |
| mp | string | 現在MP |
| mmp | string | 最大MP |
| condition | string | メモ |
| detail_a | string | 詳細A |
| detail_b | string | 詳細B |
| detail_c | string | 詳細C |
| macro | string |
マクロ マクロの文字列構成はマクロ名と実行コマンドを「|」で区切り、マクロごとに「^」で区切っています。 ＜例＞ マクロ名|実行コマンド マクロ名|実行コマンド^マクロ名|実行コマンド |
| tag | string |
タグ タグの文字列構成は名称と値を「|」で区切り、タグごとに「^」で区切っています。 ＜例＞ 名称|値 名称|値^名称|値 |
| designated | integer |
0=共有キャラクターシート 1=専用キャラクターシート |
| display_detailc | integer |
0=詳細Cをキャラクター詳細ページで表示する 1=詳細Cをキャラクター詳細ページで表示しない |
| display_macro | integer |
0=マクロ情報をキャラクター詳細ページで表示する 1=マクロ情報をキャラクター詳細ページで表示しない |
| display_tag | integer |
0=タグ情報をキャラクター詳細ページで表示する 1=タグ情報をキャラクター詳細ページで表示しない |
| outer_url | string | 外部URL |
新しいキャラクターの追加
新しいキャラクターを追加します。
エンドポイントURL
POST https://trpgsession.click/api/addchar.php
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| name | string |
[必須]
キャラクター名
|
| game_type | string |
[必須]
TRPGシステム名
|
| image | string | キャラクター画像データ（base64） |
| hp | string | 現在HP |
| mhp | string | 最大HP |
| mp | string | 現在MP |
| mmp | string | 最大MP |
| condition | string | メモ |
| detail_a | string | 詳細A |
| detail_b | string | 詳細B |
| detail_c | string | 詳細C |
| macro | string |
マクロ マクロの文字列構成はマクロ名と実行コマンドを「|」で区切り、マクロごとに「^」で区切ります。 ＜例＞ マクロ名|実行コマンド マクロ名|実行コマンド^マクロ名|実行コマンド |
| tag | string |
タグ タグの文字列構成は名称と値を「|」で区切り、タグごとに「^」で区切ります。 ＜例＞ 名称|値 名称|値^名称|値 |
| designated | integer |
0=共有キャラクターシート 1=専用キャラクターシート |
| display_detailc | integer |
0=詳細Cをキャラクター詳細ページで表示する 1=詳細Cをキャラクター詳細ページで表示しない |
| display_macro | integer |
0=マクロ情報をキャラクター詳細ページで表示する 1=マクロ情報をキャラクター詳細ページで表示しない |
| display_tag | integer |
0=タグ情報をキャラクター詳細ページで表示する 1=タグ情報をキャラクター詳細ページで表示しない |
| outer_url | string | 外部URL |
返却されたJSONの例を示します。
{
"success":"all_success_add_charcter",
"success_description":"新しいキャラクターの追加に成功"
}
既存キャラクターに新しいキャラクター情報を上書き
指定のキャラクターデータを上書きします。
エンドポイントURL
POST https://trpgsession.click/api/updatechar.php
パラメータ
| パラメータ名 | 値の種類 | 説明 |
|---|---|---|
| id | string |
[必須]
キャラクターID
|
| name | string | キャラクター名 |
| image | string | キャラクター画像データ（base64） |
| hp | string | 現在HP |
| mhp | string | 最大HP |
| mp | string | 現在MP |
| mmp | string | 最大MP |
| condition | string | メモ |
| detail_a | string | 詳細A |
| detail_b | string | 詳細B |
| detail_c | string | 詳細C |
| macro | string |
マクロ マクロの文字列構成はマクロ名と実行コマンドを「|」で区切り、マクロごとに「^」で区切ります。 ＜例＞ マクロ名|実行コマンド マクロ名|実行コマンド^マクロ名|実行コマンド |
| tag | string |
タグ タグの文字列構成は名称と値を「|」で区切り、タグごとに「^」で区切ります。 ＜例＞ 名称|値 名称|値^名称|値 |
| designated | integer |
0=共有キャラクターシート 1=専用キャラクターシート |
| display_detailc | integer |
0=詳細Cをキャラクター詳細ページで表示する 1=詳細Cをキャラクター詳細ページで表示しない |
| display_macro | integer |
0=マクロ情報をキャラクター詳細ページで表示する 1=マクロ情報をキャラクター詳細ページで表示しない |
| display_tag | integer |
0=タグ情報をキャラクター詳細ページで表示する 1=タグ情報をキャラクター詳細ページで表示しない |
| outer_url | string | 外部URL |
返却されたJSONの例を示します。
{
"success":"all_success_update_charcter",
"success_description":"キャラクター情報の更新に成功"
}