calckey/src/docs/stream.ja.md

# ストリーミングAPI

ストリーミングAPIを使うと、リアルタイムで様々な情報(例えばタイムラインに新しい投稿が流れてきた、メッセージが届いた、フォローされた、など)を受け取ったり、HTTPリクエストを発生させることなくAPIにアクセスしたりすることができます。

## ストリームに接続する

以下のURLに**websocket**接続します。
```
%URL%
```

接続する際は、`i`というパラメータ名で認証情報を含めます。例:
```
%URL%/?i=xxxxxxxxxxxxxxx
```

## ストリームを経由してAPIリクエストする

ストリームを経由してAPIリクエストすると、HTTPリクエストを発生させずにAPIを利用できます。そのため、コードを簡潔にできたり、パフォーマンスの向上を見込めるかもしれません。

ストリームを経由してAPIリクエストするには、次のようなメッセージをストリームに送信します:
```json
{
	type: 'api',
	id: 'xxxxxxxxxxxxxxxx',
	endpoint: 'notes/create',
	data: {
		text: 'yee haw!'
	}
}
```

`id`には、APIのレスポンスを識別するための、APIリクエストごとの一意なIDを設定する必要があります。UUIDや、簡単な乱数のようなもので構いません。

`endpoint`には、あなたがリクエストしたいAPIのエンドポイントを指定します。

`data`には、エンドポイントのパラメータを含めます。

<div class="ui info">
	<p><i class="fas fa-info-circle"></i> APIのエンドポイントやパラメータについてはAPIリファレンスをご確認ください。</p>
</div>

### レスポンスの受信

APIへリクエストすると、レスポンスがストリームから次のような形式で流れてきます。

```json
{
	type: 'api-res:xxxxxxxxxxxxxxxx',
	body: {
		...
	}
}
```

`xxxxxxxxxxxxxxxx`の部分には、リクエストの際に設定された`id`が含まれています。これにより、どのリクエストに対するレスポンスなのか判別することができます。

`body`には、レスポンスが含まれています。