">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Technical Specification » Persistence API

Persistence API

The Persistence API provides functionality to manage key-value pairs of information (persistent data) attached to each mixi Appli and user, and saved on mixi's servers. It's also possible to read the data of a user's friends.

This document explains how to use the Persistence API.

For more information about persistent data, see “Information Sharing”.

Prerequisites

To use the Persistence API, you are required to have the following information beforehand.

  • An access token authorized for the “mixi_apps2” scope

You can only access the Persistence API with an authorized access token as mentioned above. Currently, the mixi_apps2 scope is only available through “mixi API SDK for Android™” or “mixi API SDK for iOS”.

Functions provided by the Persistence API, and the necessary scope

The functions of the Persistence API are available within single scope.

Scope Functions Method
mixi_apps2 Writing the user's data
Reading the user's or friends' data
Deleting the user's data
POST, PUT
GET
DELETE

For more information, see mixi API SDK for Android™'s “Initialization and authorization process” and mixi API SDK for iOS' “Initialization and authorization process”.

Writing data

The Persistence API's writing features allow saving data related to the user.

POST https://api.mixi-platform.com/2/apps/appdata/@me/@self
PUT https://api.mixi-platform.com/2/apps/appdata/@me/@self
  • Both POST and PUT methods are available, but the functionality is the same.

The request body should contain key-value pairs in the application/json format as follows.

{
    "greeting" : "Welcome!",
    "level" : "5"
}

Normally, the response below will be returned.

{
    "response_code" : 200
}

Error codes

Condition Status code error value error_description value Details
Unsupported Content-Type 400 bad_request Bad request
Key/Value is invalid 400 parameter_invalid No key/value pairs
100 or more key-value pairs 413 request_entity_too_large Too many key/value pairs (max=Max number of pairs) Up to 99 keys can be saved per request.
Capacity limit exceeded 400 parameter_invalid Limit exceeded size quota (max=Capacity) A maximum of 10,000,000 bytes can be saved per mixi Appli for each user.

For details about error responses, see the Common error codes section.

Reading data

The Persistence API allows reading data in these three ways.

  • The user's own data
  • All of the user's friends' data
  • A specific user's data (the authorized user or a friend)

It's possible to specified which fields (keys) are to be retrieved.

GET https://api.mixi-platform.com/2/apps/appdata/[User-ID]/[Group-ID]?fields=[Field list]
Parameter Value to be specified
User-ID User ID for the approved user or “@me”
Group-ID “@self” or “@friends”
fields A comma-separated list of the requested keys. “*” or “@all” means all the keys. The default is to return all keys.
(Optional parameter)
  • The default value of the “fields” parameter is “*” (all).

Request examples

GET https://api.mixi-platform.com/2/apps/appdata/@me/@self
GET https://api.mixi-platform.com/2/apps/appdata/@me/@friends
GET https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=greeting,level

Deleting data

The Persistence API allows deleting the authenticated user's data. Data of other users cannot be deleted.

DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=[Field list]
Parameter Value to be specified
fields A comma-separated list of the requested keys. “*” or “@all” means all the keys. The default is to return all keys.
(Optional parameter)

Request examples

DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self
DELETE https://api.mixi-platform.com/2/apps/appdata/@me/@self?fields=greeting,level

Common error codes

When an error occurs, a response with a status code of 4xx or 5xx will be returned together with a response body in JSON format with details about the error.

Condition Status code error value error_description value Details
Permission denied (invalid selector) 403 permission_denied Permission denied
Too many write/delete requests (over 180 per 180 seconds) 503 service_unavailable appdata update frequency is too high See the Retry-After header for the number of seconds to wait
Invalid value (null, array, hash, etc.) 400 bad_request No value associated with specified key. The value should be a string
{
    "error" : "status_conflicted",
    "error_description" : "status cannot be changed"
}

Usage limitations

  • Each key can hold a string of up to 65535 bytes.
  • Up to 99 keys can be written in the same request.
  • Up to 10,000,000 bytes can be used per mixi Appli for each user.
  • Up to 180 write/delete requests can be done within 180 seconds. This limit applies to each user for each mixi Appli.

* Number of bytes of wide characters are counted as UTF-8.
* These limitations are the same as for the RESTful API.

Paging, Format

The Persistence API does not support paging, and only the JSON format is supported.

TOP OF THIS PAGE