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

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.net/img/basic/common/noimage_member76.gif",
    "nickname":"ミクシィ開発部",
    "lastLogin":"2009-06-01T12:10:05Z",
    "isViewer":"true",
    "hasApp":"true",
    "isOwner":"true",
    "id":"xxxxxxx",
    "updated":"2009-06-01T12:11:31Z",
    "userHash":"xxxxxxxxxx",
    "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>
        <nickname>ミクシィ開発部</nickname>
        <thumbnailUrl>http://img.mixi.net/img/basic/common/noimage_member76.gif</thumbnailUrl>
        <lastLogin>2009-06-01T12:10:05Z</lastLogin>
        <userHash>xxxxxxxxxx</userHash>
      </person>
    </content>
    <title/>
    <updated>2009-06-01T12:11:31Z</updated>
    <author/>
    <id>urn:guid:mixi.jp:xxxxxxx</id>
    <link href="http://img.mixi.net/img/basic/common/noimage_member76.gif" rel="alternate" type="image/jpeg"/>
  </entry>
  <osearch:startIndex>0</osearch:startIndex>
  <osearch:totalResults>1</osearch:totalResults>
</feed>

取得可能なフィールド一覧

基本情報

プロフィール情報

その他

基本情報以外の項目を取得する場合は、以下のように 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には、取得したいユーザのIDを指定します。上記の例では、xoauth_requestor_id値により指定されたユーザの友人一覧にpidで指定したユーザが含まれている場合は、そのユーザのプロフィール情報が結果として得られます。それに対して、もし友人一覧に含まれていない場合は、エラーコードとして404が返却されます。

つまり、プロフィール情報が取得できたかどうかで、友人かどうかを判断することが可能となります。

エラーコード

Person & Friends APIの呼び出し時に、いくつか結果として得られる可能性があるエラーコードがあります。これらのエラーコードは、HTTPレスポンスのHTTPステータスコードとして返却されます。エラーコードの種別によって、適切な処理を行ってください。

リクエスト削除API

指定されたリクエストを削除することができます。HTTP MethodはDELETEのみサポートされます。

/requests/@me/@self?requestIds={array}

指定可能なフィールドは以下となります。

利用可能なクエリーパラメータ

これらのクエリーパラメータは上記で紹介したAPIにて利用することができる追加のqueryパラメータです。startIndexとcountパラメータはOpenSearch仕様に基づいて解釈されます。

format={format}		-- 出力フォーマット（atomまたはjson)、デフォルトはjson
count={count}		-- ページコレクションのページサイズ
fields={field}		-- 結果に含めたいフィールドのリスト
startIndex={startIndex}	-- ページコレクションのインデックス
filterBy={fieldname}	-- 指定されたフィールドでフィルタされます（hasAppのみ対応）

guidについて

各APIの{guid}には、mixiのユーザIDを指定します。
ユーザIDを直接指定するか、ユーザIDの先頭に mixi.jp: を付加した書式を利用してください。

取得できる情報について

個人情報や他のユーザーの情報を扱うAPIについて、mixi Platformでは取得や更新に関して一定のルールを定め、情報へのアクセスに関する制限を行っています。このルールのことを「パーミッションモデル」呼びます。

PC版のみ対応mixiアプリからのRESTful APIについてのパーミッションモデルは、取得できる情報についてにて説明された内容が適用されます。

ユーザハッシュについて

プロフィール情報を取得する際に、fieldsパラメータに”userHash”を指定することで、ユーザハッシュという識別子を得ることができます。ユーザハッシュとは、「”mixiにユーザ登録した際に使用した携帯電話端末の情報”と”mixiアプリID”を元に生成した文字列」です。つまり、あるユーザがmixiに入退会を繰り返したとしても、同じ携帯端末を使って入退会した場合には、ユーザIDが変わったとしても、ユーザハッシュは同じ文字列となります。

ユーザハッシュを使うことで、入退会を繰り返すことで異なるユーザIDを取得しながらmixiアプリを利用しているユーザを検出することが可能となります。具体的には、以下の手順で検出を行うことができます。

1. People APIにて、ユーザIDとユーザハッシュを取得し、それらを組み合わせて記録しておく。
2. そのユーザが入退会を行うことで別のユーザIDを取得し、同じmixiアプリが利用される。
3. People APIにて、そのユーザIDのユーザハッシュを取得する。
4. 記録していたユーザハッシュを検索し、既に同じユーザハッシュが存在した場合は、記録していたユーザIDと新しいユーザIDは、同一のユーザと見なすことができる。

これによって、例えば入退会を繰り返すことで、mixiアプリの招待機能を繰り返し利用し不正にインセンティブを得る、といった行為をある程度抑止することができるようになります。

参考文献：

OpenSocial Restful Protocol v0.8.1
http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-protocol