Back to top

OpenFRESH (β公開中)

OpenFRESHは生放送動画配信プラットフォーム FRESH! を便利に利用するための開発者向けプロジェクトです。

現在β公開中

現在、OpenFRESH APIはβ公開中です。一部のAPIにはアクセストークンが必要ですが、FRESH!の配信用アカウントを保持しているユーザーであればアクセストークンを取得することができます。

エンドポイントは https://openapi.freshlive.tv です。

更新履歴

2017.05.05

  • FRESH!のアップデートにより、ユーザー名を記名したコメントの投稿ができるようなります

  • GET /v1/comments のレスポンスに username(ユーザー名) を追加

  • POST /v1/comments のリクエストパラメータに isSigned(記名投稿フラグ) を追加

2017.03.13

  • OpenFRESH API 初稿公開

認証

認証が必要なAPIを利用するにはアクセストークンが必要となる。アクセストークンの取得はFRESH!のアカウント(現在は配信主アカウントのみ)のログインアカウントを利用する必要がある。

OAuth

アクセストークンの取得
POST/v1/oauth/token

OpenFRESH APIを利用するためのアクセストークンを取得する。JSONレスポンスに含まれるtokenの内容がアクセストークンとなる。

Example URI

POST https://openapi.freshlive.tv/v1/oauth/token
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "your_account",
  "password": "your_password"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "username",
    "password"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "meta": "Hello, world!",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjE2IiwiZXhwx3oxNTE5OTc3Mjk1LCJzdGF0dXMiOiJicm9hZGNhc3QifQ.sTyTldvZ9H95ZsJfzMDUH2YgNGd3wYKV926tR90OjA2",
    "expiredAt": "2018-03-03T22:07:45.038+09:00"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "meta": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "token": {
          "type": "string",
          "description": "アクセストークン"
        },
        "expiredAt": {
          "type": "string",
          "description": "アクセストークンの有効期限"
        }
      },
      "required": [
        "token",
        "expiredAt"
      ]
    }
  }
}

アクセストークンの利用

リクエストヘッダ

コメント投稿APIのような認証が必要なAPIには Authorization リクエストヘッダを必ず付与するようにし、前述で取得したアクセストークンを以下のように設定する。

$ curl -X POST \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjE2IiwiZXhwx3oxNTE5OTc3Mjk1LCJzdGF0dXMiOiJicm9hZGNhc3QifQ.sTyTldvZ9H95ZsJfzMDUH2YgNGd3wYKV926tR90OjA' \
-H 'Content-Type: application/json' \
-d '{
  "programId": "70375",
  "comment": "hello!"
}' \
'https://openapi.freshlive.tv/v1/comments'

コメント

Comments

コメントの取得
GET/v1/comments

番組のコメントを取得します。生放送中はレスポンスのmeta.nowMillisecondに番組開始からの時間が含まれるので、これを次回のAPIリクエストのsinceMillisecondに指定するような実装をすると継続的にコメントを取得することができます。 番組のprogramIdを指定する必要があり、programIdは番組URLの以下の部分を指しています。

programId

Example URI

GET https://openapi.freshlive.tv/v1/comments
URI Parameters
HideShow
programId
number (required) Example: 11111

番組ID

limit
number (required) Default: 20 Example: 50

取得するコメントの件数

sinceMillisecond
number (required) Default: 0 Example: 100000

コメントを取得する番組開始からの時間(ミリ秒)

order
string (required) Default: asc Example: asc

ソート順

Choices: asc desc

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "meta": {
    "nowMillisecond": 36892765,
    "latestMillisecond": 29754707
  },
  "data": {
    "id": "9eeff70f-6f0e-40b0-ae94-7ae34c38d2ae",
    "type": "user",
    "freshId": "9999999",
    "username": "FRESH!さん",
    "programId": "11111",
    "millisecond": 10000,
    "raw": "こんにちはこんにちは @フレッシュ",
    "text": "こんにちはこんにちは",
    "atmark": [
      "フレッシュ"
    ],
    "createdAt": "2017-03-09T06:16:45+09:00"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "meta": {
      "type": "object",
      "properties": {
        "nowMillisecond": {
          "type": "number",
          "description": "番組開始からの経過時間(ミリ秒) アーカイブの場合はnull"
        },
        "latestMillisecond": {
          "type": "number",
          "description": "取得したコメントデータのうち、最も最近なコメントのmillisecond"
        }
      }
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "コメントを識別する一意なID"
        },
        "type": {
          "type": "string",
          "description": "投稿したユーザーの種別"
        },
        "freshId": {
          "type": "string",
          "description": "FRESH ID(ユーザーを識別するID)"
        },
        "username": {
          "type": "string",
          "description": "ユーザー名"
        },
        "programId": {
          "type": "string",
          "description": "番組ID"
        },
        "millisecond": {
          "type": "number",
          "description": "番組開始から対象のコメント時間までの時間(ミリ秒)"
        },
        "raw": {
          "type": "string",
          "description": "コメント本文"
        },
        "text": {
          "type": "string",
          "description": "コメント本文から `@xxx` のようなメタトークンを取り除いたもの"
        },
        "atmark": {
          "type": "array",
          "description": "コメントに `@xxx` のような文字列が含まれている場合、それを取り出した内容"
        },
        "createdAt": {
          "type": "string",
          "description": "コメントの投稿時間"
        }
      },
      "required": [
        "id",
        "type",
        "freshId",
        "programId",
        "millisecond",
        "raw",
        "text",
        "atmark",
        "createdAt"
      ]
    }
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 404,
    "message": "programId=100000 is not found.",
    "errorData": {}
  }
}

コメントの投稿
POST/v1/comments

配信中の番組にコメントを投稿します。アーカイブになってしまった番組にコメントを投稿することは出来ません。

Example URI

POST https://openapi.freshlive.tv/v1/comments
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer 取得したアクセストークン
Body
{
  "programId": "11111",
  "comment": "こんにちはこんにちは",
  "isSigned": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "programId": {
      "type": "string",
      "description": "コメントを投稿する番組ID"
    },
    "comment": {
      "type": "string",
      "description": "コメント内容"
    },
    "isSigned": {
      "type": "boolean",
      "description": "コメントにユーザー名を記名するかどうか",
      "default": false
    }
  },
  "required": [
    "programId",
    "comment"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "meta": {},
  "data": {}
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "status": 403,
    "message": "this program is not onair.",
    "errorData": {}
  }
}

留意事項

アクセストークンの扱い

アクセストークンはJWT(Json Web Token)形式で発行され、一度発行されたアクセストークンは1年間有効です。JWTは改竄に強くセキュアですが、生成されたアクセストークンは第3者に不正利用されないように各々のユーザーで保管しておく必要があります。

RateLimit

OpenFRESH APIにRateLimit(時間単位でのAPIコール数制限)が設定されています。現在は1ホストまたは1ユーザーあたり60回/1分の制限を設けており、それを越えるAPIの利用をした場合はHTTP 429 Too Many Requestsを返します。 RateLimitに達した場合は少し待ってからAPIリクエストをし、直近1分間のリクエスト数が60回を超えないような制御をする必要があります。

Generated by aglio on 05 May 2017