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.