新リクエストAPI << mixi Developer Center (ミクシィデベロッパーセンター)

新リクエストAPI

新リクエストAPIとは、mixiアプリ上でユーザからユーザへのリクエストを送る事ができる機能です。

また、それらリクエストを、 Push通知やメール等で、ユーザーへお知らせすることができます。

ここでは、新リクエストAPIについてその使用方法を説明します。

1 事前に必要なもの
2 ユーザからユーザへのリクエストの投稿
- 2.1 リクエストの投稿仕様
  - 2.1.1 recipientIdsで指定できるユーザについて
- 2.2 レスポンス仕様
- 2.3 エラー仕様
- 2.4 利用制限
3 mixiアプリ運営者からユーザへのお知らせの投稿
- 3.1 お知らせの投稿仕様
  - 3.1.1 recipientIdsで指定できるユーザについて
- 3.2 レスポンス仕様
- 3.3 エラー仕様
- 3.4 利用制限
- 3.5 注意事項

事前に必要なもの

新リクエストAPIを利用するためには以下の情報を既に入手している必要があります。
新リクエストAPIの使用する機能によって必要なスコープとアクセストークンの取得方法が異なります。

使用する機能	アクセストークン
ユーザからユーザへのリクエストの投稿	"mixi_apps2"スコープについてユーザ認可によって得られたアクセストークン
mixiアプリ運営者からユーザへのお知らせの投稿	クライアント認証によって得られたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、新リクエストAPIにアクセスすることはできません
現状では、mixi_apps2スコープはmixiアプリからのみ利用することが可能です。

クライアント認証の手順

クライアント認証されたアクセストークンを取得するためのURIは以下の仕様となります。

POST https://secure.mixi-platform.com/2/token

以下のパラメータをリクエストボディにapplication/x-www-form-urlencoded形式で指定します。

パラメータ名	指定する値
grant_type	"client_credentials"
client_id	client_id
client_secret	Consumer Secret

各パラメータが正しければ、レスポンスで以下のようなJSON形式の認可情報を返します。

{
"refresh_token":"391e1188f707bc5d599d53c3f7b13664ba2fc3d3",
 "expires_in":900,
 "access_token":"5d73a24c593234f17f389d3221225aa635a6a796",
 "token_type":"Bearer"
 }

フィールド名	説明
refresh_token	アクセストークンを更新する際に利用するリフレッシュトークン文字列
expires_in	アクセストークンが失効するまでの時間(秒)
access_token	アクセストークン文字列
token_type	アクセストークンの種類。"Bearer"という値が返されます。

ユーザからユーザへのリクエストの投稿

新リクエストAPI機能により、mixiアプリで遊んでいるユーザから別のユーザに対してリクエストを送ることができます。

リクエストの受け取りユーザとして指定できるユーザについては「 recipientIdsで指定できるユーザについて」をご覧下さい。

リクエストの投稿仕様

新リクエストAPIを利用するための URI は以下となります。

ユーザからユーザへのリクエストを投稿する際には ユーザ認可によって得られたアクセストークン を利用してくだい。

POST https://api.mixi-platform.com/2/apps/requests/[User-ID]

パラメータ名	指定する値
User-ID	認可を得た投稿者であるユーザーのユーザーID、もしくは @me が指定可能です

リクエストのリクエスト・ボディには、投稿内容をJSON形式で指定します。

Content-Type ヘッダには、 application/json と charset を指定します。

例えば本文に指定する文字列の文字コードがUTF-8 の場合は、 application/json; charset=utf-8 となります。

リクエスト・ボディに指定できるパラメータは以下の通りです。

パラメータ名	指定する値	必須か否か
body	全角・半角共に50文字以内	必須
recipientIds	リクエストを受け取るユーザのID (複数指定可能、15人まで)	必須
url	mixiアプリで用いられるアプリを起動するURL 省略された場合は、対象アプリを起動するURL 例：http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...	省略可
mediaItem	下記のパラメータを持ったオブジェクト	省略可
mediaItem.mimeType	指定する画像のMIME Type	mediaItemを利用する場合必須、指定しない場合は省略
mediaItem.url	指定したい画像のURL	mediaItemを利用する場合必須、指定しない場合は省略

urlには、クエリパラメータとしてappParamsを設定することができます。

appParamsはJSON形式で表しURIエスケープします。

appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、

mixiアプリ for TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。

（例：「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」）

appParams=%7B%22uid%22%3A%221569%22%7D

例えば、リクエストボディとして、送信内容を以下のように application/json 形式にて指定します。

{
    "body" : "ボスが強い！助けて！",
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
    "url" : "http://mixi.jp/run_appli.pl?id=1234567890&appParams=%7B%22foo%22%3A%22bar%22%7D",
    "mediaItem" : {
      "mimeType" : "image/jpeg",
      "url" : "http://hogefuga.com/piyo.jpeg"
    }
}

recipientIdsで指定できるユーザについて

recipientIdsに指定するユーザはどちらかの条件を満たしている必要があります。

リクエストを投稿しようとしているmixiアプリユーザ（User-IDで指定されている）の友人である

もしくは

リクエストを投稿しようとしているmixiアプリをインストールしている

前者の場合、mixiアプリをインストールしているかどうかによらずリクエストを投稿することが出来ます。

後者の場合は、友人であるかどうかによりません。

レスポンス仕様

正常に処理が行われた結果、新リクエストAPI は以下のレスポンスを application/json 形式で返却します。

HTTPステータスコードは、200が返却されます。

項目名	説明
recipientIds	リクエストを受け取るユーザのID
requestId	投稿したリクエストのID

例えば、以下の様なレスポンスが application/json 形式で返却されます。

{
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
    "requestId" : "115f89503138416a242f40fb7d7f338e"
}

エラー仕様

正常に処理が行われなかった際には、以下のエラーが返却されます。

状況	ステータスコード	error値	error_desription値
リクエストの Content-Type に application/json 以外が指定された	400	bad_request	Invalid Content Type
不正な User-ID	400	bad_request	Invalid User ID
mixi_apps2 スコープの認可を得ていない	401	unauthorized	Unauthorized
リクエストの受け取りユーザのユーザーのIDが不正	400	parameter_invalid	Invalid Recipient IDs
上記以外の何らかのリクエストパラメータが不正	400	parameter_invalid	Parameter Invalid
上記以外の何らかの理由でアクセス出来なかった	403	forbidden	Forbidden
API側で何らかの理由で失敗した	500	internal_server_error	Internal Server Error
制限を超えた頻度でリクエストが送られた（60秒間に1回）	503	service_unavailable	Service Unavailable

例えば、不正な User-ID が指定された場合は、以下の様なエラーレスポンスが application/json 形式で返却されます。

{
    "error" : "bad_request",
    "error_description" : "Invalid User ID"
}

利用制限

60秒間に1回まで登録ができます。mixiアプリ・ユーザごとの制限になります。

mixiアプリ運営者からユーザへのお知らせの投稿

新リクエストAPIの機能により、「mixiアプリ運営者」から 「mixiアプリをインストールしている任意のユーザ」へリクエストを投稿できるようになります。

お知らせの投稿仕様

新リクエストAPIを利用するための URI は以下となります。APIを呼び出すときはクライアント認証によって得られたアクセストークンを利用してくだい。

POST http://api.mixi-platform.com/2/apps/requests/[User-ID]

※ユーザからユーザへの投稿とURIの形式は同じですが、アクセストークンを取得する方法によって機能が変わります。

パラメータ名	指定する値
User-ID	@me だけが指定可能です

※mixiアプリ運営者からユーザへのお知らせの投稿の場合、 @me は投稿者であるmixiアプリを表しています。

HTTPリクエストのリクエスト・ボディには、投稿内容をJSON形式で指定します。
Content-Type ヘッダには、 application/json と charset を指定します。
例えばUTF-8 の場合は、 application/json; charset=utf-8 となります。

パラメータ名	指定する値	必須か否か
body	全角・半角共に50文字以内	必須
recipientIds	リクエストを受け取るユーザのID mixiアプリ運営者からユーザへのお知らせの投稿の場合は、1人のみ指定可能です。	必須
url	mixiアプリで用いられるアプリを起動するURL 省略された場合は、対象アプリを起動するURL 例：http://mixi.jp/run_appli.pl?id=[アプリID]&appParams=...	省略可
mediaItem	下記のパラメータを持ったオブジェクト	省略可
mediaItem.mimeType	指定する画像のMIME Type	mediaItemを利用する場合必須、指定しない場合は省略
mediaItem.url	指定したい画像のURL	mediaItemを利用する場合必須、指定しない場合は省略

urlには、クエリパラメータとしてappParamsを設定することができます。
appParamsはJSON形式で表しURIエスケープします。
appParams以外のパラメータ名を指定した場合でもアプリの起動URLとしてパラメータは付与されますが、
mixiアプリ for TouchにおいてはappParamsで指定したパラメータのみバックエンドサーバへ送信されます。
（例：「{"uid":"1569"}」をURIエスケープして「%7B%22uid%22%3A%221569%22%7D」）

appParams=%7B%22uid%22%3A%221569%22%7D

例えば、リクエストボディとして、送信内容を以下のように application/json 形式にて指定します。

{
    "body" : "ボス討伐イベント期間が始まりました",
     "recipientIds" : ["rdqz7s6ew176q"],
     "url" : "http://mixi.jp/run_appli.pl?id=1234567890&appParams=%7B%22foo%22%3A%22bar%22%7D",
     "mediaItem" : {
       "mimeType" : "image/jpeg",
       "url" : "http://hogefuga.com/piyo.jpeg"
     }
 }

recipientIdsで指定できるユーザについて

recipientIdsに指定するユーザは以下の条件を満たしている必要があります。

リクエストを投稿しようとしているmixiアプリをインストールしている

レスポンス仕様

正常に処理が行われた結果、新リクエストAPIは以下のレスポンスを application/json 形式で返却します。HTTPステータスコードは、200が返却されます。

項目名	説明
recipientIds	リクエストを受け取るユーザのID
requestId	投稿したリクエストのID

例えば、以下の様なレスポンスが application/json 形式で返却されます。

{
    "recipientIds" : ["rdqz7s6ew176q", "kgon1ryo7omkn"],
     "requestId" : "115f89503138416a242f40fb7d7f338e"
 }

エラー仕様

正常に処理が行われなかった際には、以下のエラーが返却されます。

状況	ステータスコード	eroor値	error_desription値
リクエストの Content-Type に application/json 以外が指定された	400	bad_request	Invalid Content Type
不正な User-ID	400	bad_request	Invalid User ID
リクエストの受け取りユーザのIDが不正	400	parameter_invalid	Invalid Recipient IDs
上記以外の何らかのリクエストパラメータが不正	400	parameter_invalid	Parameter Invalid
上記以外の何らかの理由でアクセス出来なかった	403	forbidden	Forbidden
API側で何らかの理由で失敗した	500	internal_server_error	Internal Server Error
制限を超えた頻度でリクエストが送られた	503	service_unavailable	Service Unavailable

例えば、不正な User-ID が指定された場合は、以下の様なエラーレスポンスが application/json 形式で返却されます。

{

"error" : "bad_request",
"error_description" : "Invalid User ID"
}

利用制限

4時間に1回まで投稿ができます。mixiアプリ・ユーザごとの制限になります。
ユーザはmixiアプリ運営者からユーザへ投稿されたお知らせとして最後に投稿されたもののみ受け取ることが可能であり、最新の1件以外は削除されます。

注意事項

クライアント認証の場合、Consumer Secret が漏れると、ユーザの認可なく第三者からリクエストを送られる可能性がありますので、この API を使う際に Consumer Secret はサーバーサイドに置き、より厳重な Secret の管理を必ずお願いします。

このページの上部へ

mixi Developer Center (ミクシィ デベロッパーセンター)

mixi Connect