テレビ会議/ウェブ会議を組み込める

現在の位置

FrontPage > APIReference0

SOBA Web API リファレンス

この文書はSOBA Web APIのリファレンスです。 APIはHTTPリクエストとして実装されています。実際に開発をする場合は、ここにあるAPIを直接利用するよりもプログラミング言語ごとに用意したクライアントライブラリを利用するのが便利です。

API概要 †

↑

API一覧 †

認証用Webページ（認証API）
- SOBAが提供するユーザ認証用WebページのURLの作り方です
- 認証が成功したら、生成された認証トークンをパラメータに追加してアプリケーションのWebページに戻る
- 注意：作成したURLは他のAPIの戻り値（XML形式）とは異なりHTMLを返します。このURLはプログラムからではなくウェブブラウザでアクセスするためのものです
ログイン
- ユーザの認証トークンを取得する
ログアウト
- 認証トークンを破棄する。
- SOBAをシャットダウンするcommand.mkdのURLを返す。
セッション開始
- 開始するセッションの情報を送って、セッションを開始するためのcommand.mkdのURLを取得する。
セッション参加
- 参加するセッションのIDを送って、セッションに参加するためのcommand.mkdのURLを取得する。
セッション登録
- 作成するセッションの情報を送って、セッションを開始または参加するためのURLを取得する。
セッション一覧を取得
- ユーザが参加できるすべてのセッションの情報をリストで返す。
ユーザ一覧を取得
- ユーザが見ることのできる他のユーザの情報をリストで返す。

↑

注意事項 †

↑

リクエストヘッダの追加 †

以下のAPIのリクエストにはAuthorizationヘッダを追加する必要があります。

セッション開始
セッション参加
セッション登録
セッション削除
セッション一覧を取得
ユーザ一覧を取得

これらの操作は各ユーザに固有の情報を取得するものであるため、ユーザを認証するための情報を必要とします。それがAuthorizationヘッダです。ヘッダの詳しい内容はこちらをご覧ください。

↑

ユーザ認証トークンの取得 †

Authorizationヘッダを作成するにはユーザの認証情報を表す文字列である認証トークンが要ります。その認証トークンを取得するためのAPIが次の2つです。

認証用Webページ
ログイン

認証用Webページは、SOBAが提供するユーザ認証のためのWebページのURLです。認証成功後に移動するURLをパラメータに与えてこのユーザ認証ページにブラウザでアクセスすると、指定したURLに認証トークンがパラメータに付加されます。 Webアプリケーション開発者はユーザのSOBAのアカウントを知る必要がありません。

一方ログインは、Webアプリケーション開発者がSOBAのアカウントの管理者でもある場合に使える手段です。これは他のAPIと同様に、プログラムで実行するものです。 SOBAのアカウントとパスワードをパラメータに与えてリクエストを投げると、その戻り値として受け取ったXML形式のデータの中に認証トークンが含まれています。

どちらのAPIも目的はユーザの認証トークンを取得することであり、取得できる認証トークンに差はありません。

↑

API仕様 †

↑

認証用Webページ（認証API） †

ユーザ認証を行うWebページのURLはAPIキーと認証成功後に戻るページと現在時刻を元にして次のように作る。

https://web-api.soba-project.com/webapi/1/auth?api_key=(APIキー)&back_url=(認証成功後に戻るページのURL)&time=(1970年1月1日0時0分からの経過秒数)&sig=(署名)

ここで、

sig = MD5(非公開鍵 + api_key + back_url + time)
back_url = 認証成功後に戻るページをURLエンコードしたもの

である。

認証に成功するとback_urlで指定したURLに認証トークンを追加して移動する。例えばback_urlがhttp://www.example.com/index.htmlの場合、認証成功後は

http://www.example.com/index.html?token=xxxxxxxxxxxxxxxx

に移動する。

↑

ログイン †

↑

Request †

メソッド
```
POST
```

URL

https://web-api.soba-project.com/webapi/1/login

値

api_key=APIキー&user_name=ユーザ名&password=パスワード

注意点

http://web-api.soba-project.com/webapi/1/loginでも可ですが、お勧めはできません。

↑

Response †

形式

<!ELEMENT login-response (token | error)>
<!ELEMENT token #PCDATA>
<!ELEMENT error EMPTY>

<!ATTRLIST login-response result (OK|NG) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<login-response result="OK">
  <token>abcdefghijklmnopqrstuvwxyz</token>
</login-response>

↑

ログアウト †

↑

Request †

メソッド
```
GET
```

URL

http://web-api.soba-project.com/webapi/1/logout

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT logout-response (url | error)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT error EMPTY>

<!ATTRLIST logout-response result (OK|NG) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<logout-response result="OK">
  <url>（URLをHTMLエンコードしたもの）</url>
</logout-response>

↑

セッション開始 †

↑

Request †

メソッド
```
POST
```

URL

http://web-api.soba-project.com/webapi/1/create_session

値

session_name=(セッション名)&session_description=(セッションの説明)

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT create-sessioin-response (url | error)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT error EMPTY>

<!ATTRLIST create-sessioin-response result (OK|NG) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<create-sessioin-response result="OK">
  <url>（URLをHTMLエンコードしたもの）</url>
</create-sessioin-response>

↑

セッション参加 †

↑

Request †

メソッド
```
GET
```

URL

http://web-api.soba-project.com/webapi/1/join_session?session_id=(セッションID)

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT join-session-response (url | error)>
<!ELEMENT url #PCDATA>
<!ELEMENT error EMPTY>

<!ATTRLIST enter-session-response result (OK|NG) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<enter-session-response result="OK">
  <url>（URLをHTMLエンコードしたもの）</url>
</enter-session-response>

↑

セッション登録 †

URLつきのセッションを作成します。ここで作成したURLは何度でも使えるので、同じ名前、同じ説明のセッションを手軽に繰り返し利用できるようになります。

↑

Request †

メソッド
```
POST
```

URL

http://web-api.soba-project.com/webapi/1/register_session

値

session_name=(セッション名)&session_description=(セッションの説明)

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT register-session-response (url | error)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT error EMPTY>

<!ATTRLIST register-session-response result (OK|NG) #REQUIRED>
<!ATTRLIST url already-published (true|false) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

↑

セッション削除 †

「セッション登録」で登録したセッションを使用できないようにします。

↑

Request †

メソッド
```
GET
```

URL

http://web-api.soba-project.com/webapi/1/delete_session&id=(セッションID)

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT delete-session-response (error)?>
<!ELEMENT error EMPTY>

<!ATTRLIST delete-session-response result (OK|NG) #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<delete-session-response result="OK">
</delete-session-response>

↑

セッション一覧の取得 †

↑

Request †

メソッド
```
GET
```

URL

http://web-api.soba-project.com/webapi/1/session_list

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT session-list-response (session* | error)>
<!ELEMENT session (id, title, description, creator-id, created-time, deleted-time, soba-session-id)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT creator-id (#PCDATA)>
<!ELEMENT created-time (#PCDATA)>
<!ELEMENT deleted-time (#PCDATA)>
<!ELEMENT soba-session-id (#PCDATA)>
<!ELEMENT error EMPTY>

<!ATTRLIST session-list-response result CDATA #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<session-list-response result="OK">
  <session>
    <id>id1</id>
    <title>title1</title>
    <description>description1</description>
    <creator-id>creator-id1</creator-id>
    <created-time>123456789</created-time>
    <deleted-time>null</deleted-time>
    <soba-session-id>sid1</soba-session-id>
  </session>
  <session>
    <id>id2</id>
    <title>title2</title>
    <description>description2</description>
    <creator-id>creator-id2</creator-id>
    <created-time>234567890</created-time>
    <deleted-time>null</deleted-time>
    <soba-session-id>sid2</soba-session-id>
  </session>
</session-list-response>

↑

ユーザ一覧の取得 †

↑

Request †

メソッド
```
GET
```

URL

http://web-api.soba-project.com/webapi/1/user_list

追加ヘッダ
- Authorization

↑

Response †

形式

<!ELEMENT user-list-response (user* | error)>
<!ELEMENT user (name, mail, group*)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT mail (#PCDATA)>
<!ELEMENT group (#PCDATA)>
<!ELEMENT error EMPTY>

<!ATTRLIST user-list-response result CDATA #REQUIRED>
<!ATTRLIST user id ID #REQUIRED>
<!ATTRLIST error message CDATA #REQUIRED>

例

<user-list-response result="OK">
  <user>
    <id>id1</id1>
    <name>ルパン</name>
    <mail>lupin3@soba.com</mail>
    <group>Lupin</group>
  </user>
  <user>
    <id>id2</id1>
    <name>次元</name>
    <mail>daisuke@soba.com</mail>
    <group>Lupin</group>
  </user>
  <user>
    <id>id3</id1>
    <name>五右衛門</name>
    <mail>ishikawa@soba.com</mail>
    <group>Lupin</group>
  </user>
</user-list-response>

↑

Authorizationヘッダ †

ログイン以外のAPI呼び出しにはすべてAuthorizationヘッダをつける。 Authorizationヘッダの書式は次のとおり。

Authorization: SobaAuth token="認証トークン" timestamp="タイムスタンプ" nonce="Nonce" sig="署名" sigalg="署名アルゴリズム名"

token: ログイン時に発行される認証トークン
timestamp: 現在の時刻を1970年1月1日0時0分からの経過秒数
nonce: ランダムな文字列
sig: dataから作成した署名
sigalg: 書名の作成に使うアルゴリズム名

↑

署名アルゴリズム †

↑

SOBA-1 †

アカウント登録時に発行したキーとtimestamp, nonceを連結してできる文字列のMD5

例えば

キー = "abcdefghijklmnopqrstuvwxyz"
timiestamp = "100000000"
nonce = "hogefugafoobarbuz"

のとき

sig = MD5("abcdefghijklmnopqrstuvwxyz100000000hogefugafoobarbuz")

現在の位置

目次(`I`) [折り畳む]

API概要 †

API一覧 †

注意事項 †

リクエストヘッダの追加 †

ユーザ認証トークンの取得 †

API仕様 †

認証用Webページ（認証API） †

ログイン †

Request †

Response †

ログアウト †

Request †

Response †

セッション開始 †

Request †

Response †

セッション参加 †

Request †

Response †

セッション登録 †

Request †

Response †

セッション削除 †

Request †

Response †

セッション一覧の取得 †

Request †

Response †

ユーザ一覧の取得 †

Request †

Response †

Authorizationヘッダ †

署名アルゴリズム †

SOBA-1 †

メニュー

現在の位置

目次(I) [折り畳む]

API概要 †

API一覧 †

注意事項 †

リクエストヘッダの追加 †

ユーザ認証トークンの取得 †

API仕様 †

認証用Webページ（認証API） †

ログイン †

Request †

Response †

ログアウト †

Request †

Response †

セッション開始 †

Request †

Response †

セッション参加 †

Request †

Response †

セッション登録 †

Request †

Response †

セッション削除 †

Request †

Response †

セッション一覧の取得 †

Request †

Response †

ユーザ一覧の取得 †

Request †

Response †

Authorizationヘッダ †

署名アルゴリズム †

SOBA-1 †

メニュー

目次(`I`) [折り畳む]