オンセンAPIとは

ver.1.02

オンセンAPIとは、OAuth2.0を使ってTRPGオンラインセッションSNSの情報の取得や作成・編集などの機能を提供するAPIサービスです。


オンセンAPIの利用準備

はじめに

オンセンAPIを使用するには、オンセンAPIのクライアントID(client_id)とクライアントシークレット(client_secret)が必要となります。以下の手順にしたがって取得してください。


オンセンAPIが使用されるまでのフロー

流れは次のとおりです。


ステップ1:認可コード要求

認可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攻撃を防ぐためにクライアントアプリケーションで使用する一意の値。

ステップ2:認可コード返却

承認プロセス中にエラーがなく、且つユーザがアクセスを承認した場合、 APIサーバはユーザをredirect_uriで指定されたアプリケーションのURLにリダイレクトします。
アプリケーションにリダイレクトで戻ってくるときAPIサーバは2つのGETクエリパラメータが付加します。

Content-Type

text/html

返却されたパラメータ

パラメータ名 値の種類 説明
code string 認可コード。ユーザがアクセス要求を承認したことを示します。
state string 最初にリクエストを送ったときに渡したstateパラメータの値。
この値をステップ1で生成した値と比較し一致しなければ、 悪意あるユーザによってアプリケーションにCSRF攻撃がしかけられた可能性があります。 したがって、この場合はOAuthフローを中断すべきです。

ステップ3:アクセストークン要求

アクセストークン発行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 という値を指定します。 これは認可コードをアクセストークンに交換することを示します。

ステップ4:アクセストークン返却

リクエストの認証が問題なく終わり、且つパラメータが適正であれば、APIサーバはアクセストークンを生成し、JSON形式で返します。

Content-Type

application/json

次にJSON形式でエンコードされたレスポンスの例を示します。

{
  "access_token":"1234567890abcd",
  "token_type":"Bearer"
}

返却されたJSON形式パラメータ

パラメータ名 値の種類 説明
access_token string APIリクエストを認可するときに使用するトークン。
token_type string 発行されたアクセストークンの種類。

ステップ5:APIを呼び出す

全てのAPIは各APIごとのエンドポイントにステップ4で取得したアクセストークンを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":"キャラクター情報の更新に成功"
}