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
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"
]
}
200
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の以下の部分を指しています。
Example URI
- 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
200
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"
]
}
}
}
404
Headers
Content-Type: application/json
Body
{
"error": {
"status": 404,
"message": "programId=100000 is not found.",
"errorData": {}
}
}
コメントの投稿POST/v1/comments
配信中の番組にコメントを投稿します。アーカイブになってしまった番組にコメントを投稿することは出来ません。
Example URI
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"
]
}
201
Headers
Content-Type: application/json
Body
{
"meta": {},
"data": {}
}
403
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回を超えないような制御をする必要があります。