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

mixiアプリモバイルでは、ユーザのプロフィール情報や友人に関する情報などをAPIにより取得して利用することができます。各APIは、OpenSocial RESTful 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用の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",
    "platformUserId":"xxxxxxxxxxxxx",
    "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>
        <platformUserId>xxxxxxxxxxxxx</platformUserId>
      </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ステータスコードとして返却されます。エラーコードの種別によって、適切な処理を行ってください。

Persistence API

ユーザに関するデータをmixiサーバ上にKey-Value形式で格納します。

/appdata/{guid}/@self/@app
/appdata/{guid}/@friends/@app

application/json 形式:

{
  "entry" : {
    "mixi.jp:xxxxxx":{"subject":"appdata subject: 80","content":"appdata content: 86","updated":"2009-02-13T18:30:02Z"}
  },
  "startIndex":0,
  "id":["mixi.jp:xxxxxx"],
  "totalResults":1
}

application/atom+xml representation:

<?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">
      <appdata xmlns="http://ns.opensocial.org/2008/opensocial">
        <subject>appdata subject: 6</subject>
        <content>appdata content: 36</content>
        <updated>2009-02-13T18:30:02Z</updated>
      </appdata>
    </content>
    <title/>
    <updated/>
    <author>
      <url>urn:guid:mixi.jp:xxxxxxx</url>
    </author>
    <id>urn:guid:mixi.jp:xxxxxxx</id>
  </entry>
  <osearch:startIndex>0</osearch:startIndex>
  <osearch:totalResults>1</osearch:totalResults>
</feed>

エラーコード

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

Albums API

/albums/{guid}/@self

ユーザが作成したフォトアルバムに関する情報を取得できます。

application/json 形式:

{
  "entry":[{
    "thumbnailUrl":"http://ic.mixi.jp/p/xxxxx.jpg",
    "mediaItemCount":"15",
    "caption":"アルバム名",
    "id":"mixi.jp:xxxxx",
    "title":"アルバム名",
    "description":"アルバム説明",
    "ownerId":"mixi.jp:xxxxx",
    "mediaMimeType":['image/jpeg']
  }],
  "startIndex":"0",
  "itemsPerPage":"20",
  "totalResults":"2"
}

通常は全体公開に設定しているアルバムの情報のみが取得できます。’visibility=all’というパラメータを付与することによって、すべてのアルバム情報が取得できます。

/mediaitems/{guid}/@self/{albumId}

指定したアルバムIDに含まれるフォトのコレクションを取得できます。

application/json 形式:

{
  "entry":[{
    "albumId":"mixi.jp:xxxxx",
    "fileSize":"xxxxx",
    "thumbnailUrl":"http://ic.mixi.jp/p/xxxxx.jpg",
    "url":"http://ic.mixi.jp/xxxxx.jpg",
    "id":"mixi.jp:xxxxx",
    "title":"写真タイトル",
    "description":"説明"
  }],
  "startIndex":"0",
  "itemsPerPage":"20",
  "totalResults":"15"
}

リクエスト削除API

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

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

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

※xoauth_requestor_idにはリクエストを受信したユーザーのIDを指定する仕様になっていますのでご注意ください。

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

これらのクエリーパラメータは上記いずれでも利用することができる追加の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アプリモバイルにおけるパーミッションモデルについては、基本的にPC版と同じです。ただし、mixiアプリモバイルでは、アプリ利用に同意したユーザのみがアプリケーションを利用することができます。このため、VIEWER、OWNERの区別はなく、常にVIEWER=OWNERとなります。

パーミッションモデルを表にまとめたものが以下となります。

ユーザーの基本情報、プロフィール情報、友人一覧の取得

• 「●」は、取得可能を表します。
• 「○」は、「全体公開」「友人まで公開」「友人の友人まで公開」のいずれかであれば取得可能を表します。
• 「▲」は、基本的に取得可能だが、ユーザーが公開をOFFにした場合は取得できないことを表します。
• 「△」は、「全体公開」であれば取得可能だが、ユーザーが公開をOFFにした場合は取得できないことを表します。

永続化情報の取得、更新

≫ 取得できる情報について もご覧ください。

ユーザハッシュについて

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

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

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

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

新方式のユーザーIDの取得について

アプリ設定画面にてID変換APIの利用規約に同意していただいている場合、fieldsパラメータに”platformUserId”を追加することによって、新方式のユーザIDを取得できます。
例えば、以下のようなリクエストを発行します。

GET http://api.mixi-platform.com/os/0.8/people/@me/@friends?fields=platformUserId

これにより以下のようなレスポンスが得られます。

{
  "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",
    "platformUserId":"xxxxxxxxxxxxx",
    "displayName":"ミクシィ開発部"},
  "startIndex":0,
  "totalResults":1
}

各エントリ内に”platformUserId”というフィールドが含まれます。”platformUserId”の内容は以下のとおりです。

参考文献：

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