">mixi Developer Center (mDC)

mixi Apps

mixi Apps (English) » Technical Specification » PC » RESTful API for PC » RESTful API Specifications

RESTful API Specifications

RESTful API is available for the developer who is willing to develop mixi App for PC in order to obtain profile information or information related to Friends.
Each API complies with RESTful API specification described in OpenSocial.

In some cases, the information retrieved through JavaScript API may be maliciously manipulated on a website. The developer is able to mitigate such fraud by retrieving the information through RESTful API rather than JavaScript API.

Access to RESTful API requires OAuth Signature with Consumer Key and Secret. The developer can refer Access to API with 2-legged OAuth for how to generate OAuth Signature.

The end point for mixi OpenSocial RESTful API is following:

http://api.mixi-platform.com/os/0.8

Preparation

In order to use RESTful API for a mixi App that is available only for PC, the development needs to obtain Consumer Key and Secret.

If Consumer Key and Secret are not shown on the setting page for the mixi App (edit_appli.pl), current setting should be saved without any changes. With that, the Consumer Key and Secret are issued and shown on the same page.

Restriction

Some restrictions may apply to access to RESTful API when it is used for the mixi App available only for PC. It is necessary to specify who is accessing to RESTful API with xoauth_requestor_id parameter. The parameter should be a user ID. Only ID of users who run a certain mixi App on a web browser within a certain period of time can be specified.

In the case either such user doesn’t run the mixi App or access to the API is made after the certain period of time, “401 unauthorized” will be returned as http response code.

Available APIs

The following APIs are available for the mixi App only available for PC. Retrievable fields and access control are identical with the one for JavaScript API.

Person & Friends API

It enables the developer to retrieve user’s profile and information regarding Friends.

/people/{guid}/@all
/people/{guid}/@friends
/people/{guid}/@self
/people/@me/@self

The followings are sample codes to retrieve user profile.

application/json format:

{
  "entry" : {
    "thumbnailUrl":"http://img.mixi.net/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 format:

<?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.net/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.net/img/basic/common/noimage_member76.gif" rel="alternate" type="image/jpeg"/>
  </entry>
  <osearch:startIndex>0</osearch:startIndex>
  <osearch:totalResults>1</osearch:totalResults>
</feed>
Retrievable fields

Basic Information

Field Content Format
nickname nickname xs:string
profileUrl Profile URLL xs:string
thumbnailUrl Profile image URL xs:string
hasApp App usage status xs:boolean
bloodType Blood type
(A, AB, B or O)
xs:string

Profile Information

Field Content Format
addresses Current address address Element
birthday Birth date xs:date
gender Gender xs:string

Information other than the basic information can be specified by a name of the item separated by comma in the filed parameter as follows:

/people/@me/@self?format=json&fields=birthday,gender
The list of Friends who install a certain mixi App

In order to obtain the list of Friends who currently install a mixi App through Friends API, hasApp should be specified for the filterBy parameter.

/people/@me/@friends?format=json&filterBy=hasApp

By specifying only necessary data, the development is able to improve the response time. In accessing to Friends API, it is strongly encouraged to use this filter as a default setting.

Retrieve specific users from the list of Friends

The developer is capable of confirming if a certain user is a Friend with @friends/{pid} as follows:

/people/@me/@friends/{pid}

For {pid}, ID for a user to be confirmed. With an example above, the developer is able to see the profile of a user specified for {pid}, in the case the user is in the list of Friends of a user specified for xoauth_request_id. Otherwise, 404 error is returned. In other words, availability of a user profile can tell if a user is a Friend.

Error Code

In calling Person & Friends API, some error codes may be available. These error codes are returned as http status code. Analyzing these codes, the developer can determine what causes these errors and how to handle them.

Error Code Reference
400 (BAD_REQUEST) Wrong paging value, inappropriate authentication, target user IDs are not specified
403 (FORBIDDEN) No authorization, selectors (e.g. @self, @friends) are not specified
404 (NOT_FOUND) Wrong user ID, Target users are not found
500 (INTERNAL_SERVER_ERROR) mixi internal error

Available Query Parameters

The following are additional query parameters for APIs described above. startIndex and count parameter is interpreted based on OpenSearch specification.

format={format}			-- output format (atom or json)
count={count}			-- page size for page collection
fields={field}			-- list of fields to be contained in a result
startIndex={startIndex}		--index for page collection
filterBy={fieldname}		--filtering with specified field (only hasApp can be applied)

guid

mixi user ID can be specified as {guid} for each API. It can be specified as “mixi.jp:1234″ or “1234″

Available Information

For some APIs which enable to obtain and/or update user’s privacy information and/or related user’s information, mixi Platform sets out a certain rules and imposes restrictions on accesses to these information. The rules are called “permission model” and the permission model stated in “Available Information” applies for RESTful API for the mixi App only available for PC.

References

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

TOP OF THIS PAGE