PC版のみ対応mixiアプリでは、ユーザのプロフィール情報やマイミクに関する情報をRESTful APIにより取得して利用することができます。各APIは、OpenSocial RESTful APIに準拠しています。
PC向けmixiアプリについて、JavaScript APIから取得した情報は、Webブラウザ上で悪意を持ったユーザに改ざんされてしまう可能性があります。つまり、JavaScript APIにて取得した情報を、gadgets.io.makeRequest()関数などにより外部サーバに送信することを考えた場合に、その内容はユーザによって不正に変更されているかもしれない、ということになります。外部サーバからRESTful APIを利用してJavaScript APIの代わりに情報を取得することによって、悪意を持ったユーザによる改ざんの余地を最小限に留めることが可能となります。
各APIへアクセスするためには、Consumer KeyとSecretを用いた署名（OAuth Signature）をつける必要があります。OAuth Signature の生成方法については 2-legged OAuthによるAPIアクセス を参照ください。
mixi OpenSocial RESTful APIのエンドポイントは、下記になります。
http://api.mixi-platform.com/os/0.8
利用準備
PCのみ対応のmixiアプリにおいてRESTful APIを利用するためには、Consumer keyおよびsecretを発行、入手する必要があります。
mixiアプリの設定画面（edit_appli.pl）において、もしConsumer keyおよびConsumer secretが表示されていなかった場合は、一度その画面で設定内容を保存します。その際に、設定内容を変更する必要はありません。この時点で、対象のmixiアプリで利用可能なConsumer keyおよびsecretが発行され、同一ページ内にそれらが表示されます。
制限事項
PCのみ対応のmixiアプリにおいてRESTful APIを利用する際には、アクセスに関して制限があります。
RESTful APIにアクセスする際に、xoauth_requestor_idパラメータによって、誰の権限でアクセスを行うかを指定することが必要になります。パラメータ値は、対象ユーザのIDとなります。このユーザIDについて、「一定時間内にWebブラウザで対象のmixiアプリを起動したユーザ」のIDのみ指定することが可能です。
対象ユーザが対象のmixiアプリを起動していない、もしくは起動から一定時間が経過した後にRESTful APIにアクセスを行った際には、HTTPレスポンスコードとして「401 Unauthorized」が返却されます。
提供されるAPI
PC向けのみ対応のmixiアプリでは、以下のAPIが利用可能です。なお、取得可能なフィールドおよびアクセスコントロールについてはPC用のJavaScript APIと同一です。
Person & Friends API
ユーザのプロフィールやマイミクに関する情報の取得を取得することができます。
/people/{guid}/@all
/people/{guid}/@friends
/people/{guid}/@self
/people/@me/@self
application/json 形式:
{
"entry" : {
"thumbnailUrl":"http://img.mixi.jp/img/basic/common/noimage_member76.gif",
"nickname":"ミクシィ開発部",
"lastLogin":"2009-06-01T12:10:05Z",
"name":{
"formatted":"ミクシィ 開発部",
"givenName":"ミクシィ",
"familyName":"開発部"},
"isViewer":"true",
"hasApp":"true",
"isOwner":"true",
"id":"xxxxxxx",
"updated":"2009-06-01T12:11:31Z",
"displayName":"ミクシィ開発部"},
"startIndex":0,
"totalResults":1
}
application/atom+xml 形式:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:osearch="http://a9.com/-/spec/opensearch/1.1">
<entry>
<content type="application/xml">
<person xmlns="http://ns.opensocial.org/2008/opensocial">
<id>urn:guid:mixi.jp:xxxxxxx</id>
<displayName>ミクシィ開発部</displayName>
<name>
<familyName>開発部</familyName>
<formatted>ミクシィ 開発部</formatted>
<givenName>ミクシィ</givenName>
</name>
<nickname>ミクシィ開発部</nickname>
<thumbnailUrl>http://img.mixi.jp/img/basic/common/noimage_member76.gif</thumbnailUrl>
<lastLogin>2009-06-01T12:10:05Z</lastLogin>
</person>
</content>
<title/>
<updated>2009-06-01T12:11:31Z</updated>
<author/>
<id>urn:guid:mixi.jp:xxxxxxx</id>
<link href="http://img.mixi.jp/img/basic/common/noimage_member76.gif" rel="alternate" type="image/jpeg"/>
</entry>
<osearch:startIndex>0</osearch:startIndex>
<osearch:totalResults>1</osearch:totalResults>
</feed>
取得可能なフィールド一覧
基本情報
| フィールド名 |
内容 |
フォーマット |
| nickname |
ニックネーム |
xs:string |
| profileUrl |
プロフィールURL |
xs:string |
| thumbnailUrl |
プロフィール画像URL |
xs:string |
| hasApp |
アプリ利用状態 |
xs:boolean |
| bloodType |
血液型
※A, AB, B, Oのいずれか |
xs:string |
プロフィール情報
| フィールド名 |
内容 |
フォーマット |
| addresses |
現住所 |
address Element |
| birthday |
生年月日 |
xs:date |
| gender |
性別 |
xs:string |
基本情報以外の項目を取得する場合は、以下のように fields パラメータに項目名をカンマ区切りで指定します。
/people/@me/@self?format=json&fields=birthday,gender
アプリをインストールしているマイミク一覧の取得
Friends APIにて、現在のmixiアプリをインストールしているユーザのみの一覧を取得する場合は、以下のように filterBy パラメータに hasApp を指定します。
/people/@me/@friends?format=json&filterBy=hasApp
最初から必要なデータのみを取得することで、mixiアプリのレスポンス向上を図ることが可能になり、開発者およびユーザの双方にメリットがあります。Friends APIアクセス時は、基本的にこのフィルタを設定するようにしてください。
マイミク一覧から特定ユーザの取得
あるユーザがマイミクシィかどうかを確認したい場面がしばしば登場します。これを行うために、@friends/{pid}という指定を利用することができます。
/people/@me/@friends/{pid}
pidには、取得したいユーザのmember_idを指定します。上記の例では、xoauth_requestor_id値により指定されたユーザのマイミクシィ一覧にpidで指定したユーザが含まれている場合は、そのユーザのプロフィール情報が結果として得られます。それに対して、もしマイミクシィ一覧に含まれていない場合は、エラーコードとして404が返却されます。
つまり、プロフィール情報が取得できたかどうかで、マイミクシィかどうかを判断することが可能となります。
エラーコード
Person & Friends APIの呼び出し時に、いくつか結果として得られる可能性があるエラーコードがあります。これらのエラーコードは、HTTPレスポンスのHTTPステータスコードとして返却されます。エラーコードの種別によって、適切な処理を行ってください。
| エラーコード |
発生する状況 |
| 400 (BAD_REQUEST) |
ページング指定値が不正、認証情報が不正、取得対象IDが未指定 |
| 403 (FORBIDDEN) |
取得権限がない、セレクタ(@self, @sfriendsなど)が未指定 |
| 404 (NOT_FOUND) |
指定ユーザが見つからない、取得対象ユーザIDが不正 |
| 500 (INTERNAL_SERVER_ERROR) |
mixi側の内部エラー |
利用可能なクエリーパラメータ
これらのクエリーパラメータは上記で紹介したAPIにて利用することができる追加のqueryパラメータです。startIndexとcountパラメータはOpenSearch仕様に基づいて解釈されます。
format={format} -- 出力フォーマット（atomまたはjson)、デフォルトはjson
count={count} -- ページコレクションのページサイズ
fields={field} -- 結果に含めたいフィールドのリスト
startIndex={startIndex} -- ページコレクションのインデックス
filterBy={fieldname} -- 指定されたフィールドでフィルタされます（hasAppのみ対応）
guidについて
各APIの{guid}には、mixiのユーザIDを指定します。
mixi.jp:1234 または 1234 のような書式を利用してください。
取得できる情報について
個人情報や他のユーザーの情報を扱うAPIについて、mixi Platformでは取得や更新に関して一定のルールを定め、情報へのアクセスに関する制限を行っています。このルールのことを「パーミッションモデル」呼びます。
PC版のみ対応mixiアプリからのRESTful APIについてのパーミッションモデルは、取得できる情報についてにて説明された内容が適用されます。
参考文献：
OpenSocial Restful Protocol v0.8.1
http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol
