Skip to content
This repository has been archived by the owner on Jun 20, 2024. It is now read-only.

api docs (ja) of Streaming APIs

Marihachi edited this page Dec 4, 2018 · 36 revisions
Frost-API v1.0の仕様に合わせて内容の変更が進行中です。v1.0以前の仕様とは互換性はありません。

Streaming APIs


目次


WebSocketプロトコルに従って接続します。
wss://(APIサーバのドメイン名)?access_token=(AccessToken) に接続してください。

やり取りされるデータ(フレームオブジェクト)のフォーマットについて

Streaming APIsは、JSONオブジェクトをWebSocketのUTF-8メッセージとしてやり取りすることによって利用されます。
やり取りされるJSONオブジェクトは、必ず以下のプロパティを含んでいる必要があります

プロパティ名 説明
@frame 利用するAPIに関連付いたフレーム名を指定します。

Streaming APIsではこのオブジェクトのことを「フレームオブジェクト」と呼んでいます。

フレームオブジェクトの例

{
  "@frame": "frame name",
  "paramA": "this is a parameter"
}

エラー時のフレームデータに含まれるerror.reasonプロパティについて

error.reasonはReasonIdとして定義されている文字列が返されます。

ReasonIdとして定義されている値

ReasonId 説明
"serverError" サーバがリクエストの処理に失敗しました。
"userNotFound" 指定されたユーザーが見つからなかったことを表します。
"postingNotFound" 指定された投稿データが見つからなかったことを表します。
"appNotFound" 指定された連携アプリが見つからなかったことを表します。

[編集中]

Streaming Request API

各エンドポイントへのリクエストをWebSocketのコネクション上から行えるようにするAPIです。
HTTPリクエストがその都度発生しないため、オーバーヘッドを小さくすることが出来ます。

エンドポイントにリクエストする

フレームの構造(リクエスト)

{
  @frame: "request",
  id: number | string,
  endpoint: string,
  params: object?
}

フレームの構造(成功時レスポンス)

{
  @frame: "request",
  id: number | string,
  resultType: string,
  result: object
}

フレームの構造(エラー時レスポンス)

{
  @frame: "request",
  id: number | string,
  error: {reason: string(ReasonId), message: string}
}

idプロパティにnumber型の値で渡す場合、その値は整数であるべきです。小数を含む数値を渡したいときは文字列にして渡してください。

error.reasonに設定される値についてはこちらを参照してください。

リクエスト
{
  "@frame": "request",
  "id": "3",
  "endpoint": "/posting/create-chat",
  "params": {
    "text": "コーヒー1杯で1回です"
  }
}
レスポンス
{
  "@frame": "request",
  "id": "3",
  "resultType": "posting",
  "result": {
    "createdAt": 1542525441,
    "id": "5bf1120154d6cf2a485bcb6e",
    "text": "コーヒー1杯で1回です",
    "type": "chat",
    "user": {
      "createdAt": 1500702964,
      "description": "コーヒーが好きです",
      "followersCount": 7,
      "followingsCount": 16,
      "iconFileId": "5a813952bf8f203120a6b189",
      "id": "5972e8f4d61aea367cbf6972",
      "name": "香風智乃",
      "postingsCount": {
        "chat": 252
      },
      "screenName": "chino123"
    }
  }
}

EventStream API

リアルタイムにタイムラインや通知を受信するためのAPIです。

sourceNameに指定できる値
  • "homeTimeline"
  • "notification" (comming soon)

イベントストリームを購読する

フレームの構造(リクエスト)

{
  @frame: "eventStream.subscribe",
  id: number | string,
  sourceName: string
}

フレームの構造(成功時レスポンス)

{
  @frame: "eventStream.subscribe",
  id: number | string,
  result: {message: string}
}

フレームの構造(エラー時レスポンス)

{
  @frame: "eventStream.subscribe",
  id: number | string,
  error: {reason: string(ReasonId), message: string}
}

idプロパティにnumber型の値で渡す場合、その値は整数であるべきです。小数を含む数値を渡したいときは文字列にして渡してください。

sourceNameに指定できる値についてはこちらを参照してください。

error.reasonに設定される値についてはこちらを参照してください。

リクエスト
{
  "@frame": "eventStream.subscribe",
  "id": "1",
  "sourceName": "homeTimeline"
}
レスポンス
{
  "@frame": "eventStream.subscribe",
  "id": "1",
  "result": {
    "message": "subscribed home timeline"
  }
}

イベントストリームを購読解除する

フレームの構造(リクエスト)

{
  @frame: "eventStream.unsubscribe",
  id: number | string,
  sourceName: string
}

フレームの構造(成功時レスポンス)

{
  @frame: "eventStream.unsubscribe",
  id: number | string,
  result: {message: string}
}

フレームの構造(エラー時レスポンス)

{
  @frame: "eventStream.unsubscribe",
  id: number | string,
  error: {reason: string(ReasonId), message: string}
}

idプロパティにnumber型の値で渡す場合、その値は整数であるべきです。小数を含む数値を渡したいときは文字列にして渡してください。

sourceNameに指定できる値についてはこちらを参照してください。

error.reasonに設定される値についてはこちらを参照してください。

リクエスト
{
  "@frame": "eventStream.unsubscribe",
  "id": "2",
  "sourceName": "homeTimeline"
}
レスポンス
{
  "@frame": "eventStream.unsubscribe",
  "id": "2",
  "result": {
    "message": "unsubscribed home timeline"
  }
}