RESTful API仕様 << mixi Developer Center (ミクシィデベロッパーセンター)

mixiアプリの設定画面（edit_appli.pl）において、もしConsumer keyおよびConsumer secretが表示されていなかった場合は、一度その画面で設定内容を保存します。その際に、設定内容を変更する必要はありません。この時点で、対象のmixiアプリで利用可能なConsumer keyおよびsecretが発行され、同一ページ内にそれらが表示されます。

制限事項

スマートフォンのみ対応のmixiアプリにおいてRESTful APIを利用する際には、アクセスに関して制限があります。

RESTful APIにアクセスする際に、xoauth_requestor_idパラメータによって、誰の権限でアクセスを行うかを指定することが必要になります。パラメータ値は、対象ユーザのIDとなります。このユーザIDについて、「一定時間内にWebブラウザで対象のmixiアプリを起動したユーザ」のIDのみ指定することが可能です。

対象ユーザが対象のmixiアプリを起動していない、もしくは起動から一定時間が経過した後にRESTful APIにアクセスを行った際には、HTTPレスポンスコードとして「401 Unauthorized」が返却されます。

提供されるAPI

スマートフォン向けのみ対応の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>

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

基本情報

フィールド名	内容	フォーマット
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

その他

フィールド名	内容	フォーマット
userHash	ユーザハッシュ	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, @friendsなど)が未指定
404 (NOT_FOUND)	指定ユーザが見つからない、取得対象ユーザIDが不正
500 (INTERNAL_SERVER_ERROR)	mixi側の内部エラー

リクエスト削除API

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

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

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

フィールド名	内容
requestIds	リクエストIDをカンマ区切りで指定します。

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

これらのクエリーパラメータは上記で紹介した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では取得や更新に関して一定のルールを定め、情報へのアクセスに関する制限を行っています。このルールのことを「パーミッションモデル」呼びます。

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

ユーザハッシュについて

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

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

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

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

参考文献：

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

このページの上部へ

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

mixiアプリ