AppData
Overview
Appdata is a persistent data API that is provided for each user.
Appdata Object Fields
The following is a list of Appdata object fields supported by the Mobage Open Platform.
| Value | Description | Type | Namespace | Remarks |
|---|---|---|---|---|
| person_id | guid denoting persistent data owner | xs:string | http://ns.opensocial.org/2008/opensocial | – |
| entry | Persistent data | tnx:AppdataEntry (unbounded) | http://ns.opensocial.org/2008/opensocial | Collection in key-value format |
entry Field
Specify this as an array of AppdataEntry objects. The following can be defined as AppdataEntry object fields.
| Value | Description | Type | Namespace | Remarks |
|---|---|---|---|---|
| key | Persistent data key | xs:string | http://ns.opensocial.org/2008/opensocial | Maximum 32 bytes |
| value | Persistent data value | xs:string | http://ns.opensocial.org/2008/opensocial | Maximum 1024 bytes |
JSON Representations
The following representations are all handled as the same entity.
- Full representation
{
"entry": [
{ "key": "score", "value": "78" },
{ "key": "high_score", "value": "97" }
]
}
- Simple representation of AppdataEntry only
{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
- Simple representation of Appdata and AppdataEntry
{
"score": "78",
"high_score": "97"
}
Unless you have a specific reason, you should use the simple representation that includes both Appdata and AppdataEntry objects for sending data, as shown in 3.
API Request
HTTP Methods
Proxy model
- GET - Gets Appdata
- POST - Creates and updates Appdata
- PUT - Creates and updates Appdata (same behavior as POST)
- DELETE - Deletes Appdata
Trusted model
Endpoint URL
-
Sandbox environment
http://sb.sp.app.mbga.jp/api/restful/v1/appdata/{guid}/{selector}/{appid} -
Production environment
http://sp.app.mbga.jp/api/restful/v1/appdata/{guid}/{selector}/{appid}
URI Template Parameter
guid
Specify one of the following values for the guid parameter.
| Value | Description | Remark |
|---|---|---|
| @me | guid of the viewer | Required |
| {guid} | User ID | Required |
Before a valid Mobage user ID can be used with the guid parameter, the user must have installed the associated application.
selector
Only @self can be specified for the selector parameter.
| Value | Description | Remark |
|---|---|---|
| @self | Represents an Appdata collection resource of the viewer | Required |
appid
Only @app can be specified for the appid parameter.
| Value | Description | Remark |
|---|---|---|
| @app | Represents an Appdata entry resource for the application that is currently being executed | Required |
Query Parameters
format
You can specify the response format as shown below.
| Value | Description | Remark |
|---|---|---|
| json | "application/json; charset=utf8" | Optional, default value |
fields
The fields specification in Appdata is used as a key for the AppdataEntry object. This allows you to get, update or delete Appdata for a specific key. For more information, please see
OpenSocial RESTful Protocol Specification v0.9 - 9.3 Partial Updates.
OAuth Signed Request
Please see this specification to find out how to transfer data safely: OAuth Request Body Hash.
You must include xoauth_requestor_id as an Authorized header or query parameter.
Specify the following values according to the mode.
Proxy mode
guid of the viewer (value of opensocial_viewer_id sent from the Gadget Server)
API Response
Response Codes
The following is a list of the API response codes.
| Request HTTP method | Response code | Response message | Description |
|---|---|---|---|
| GET | 200 | OK | Appdata was successfully obtained |
| POST/PUT/DELETE | 202 | Accepted | Appdata was successfully created, updated or deleted |
| GET/POST/PUT/DELETE | 400 | Bad Request | Invalid request data |
| GET/POST/PUT/DELETE | 401 | Unauthorized | 0Auth authorization failed |
| GET/POST/PUT/DELETE | 403 | Forbidden | Could not access data for some reason other than because of an authentication error |
| GET/POST/PUT/DELETE | 405 | Method Not Allowed | Method is not allowed |
| GET/POST/PUT/DELETE | 500 | Internal Server Error | Request failed because of an internal API problem |
Notes
- If a GET is issued without specifying fields, it means that the entire Appdata entry will be obtained. If you know the required key in advance, you should always specify fields.
When a POST/PUT is issued without specifying fields, the entire Appdata entry will be created or updated, and the key-value pair that was resent will be saved after the previous data is deleted. For incremental updates, specify fields. - If a DELETE is issued without specifying fields, it means that the entire Appdata entry will be deleted. To delete only a specific key, specify fields.
- The maximum sizes of key and value are 32 bytes and 1024 bytes, respectively.
- A maximum of 30 key-value pairs can be saved for each user who installs an application.
- If a user sends a request using the Trusted model but has not installed the application, a response code of 403 will be returned.
- After Appdata is successfully created or updated, a response code of 202 will be returned.
Examples
Creating Appdata
This example shows how to create new Appdata.
Request format
POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8
{
"max_score" : 96,
"score" : 78
}
Or
POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8
{
"entry": [
{ "key": "max_score", "value": 96 },
{ "key": "score", "value": 78 }
]
}
or
POST /api/restful/v1/appdata/@me/@self/@app?format=json
Content-Type: application/json; charset=utf8
{
"entry": {
"max_score" : 96,
"score" : 78
}
}
Response format
201 Created
Getting Appdata for a Specific key
The following example shows how to get Appdata only for a specific key.
Request format
GET /api/restful/v1/appdata/@me/@self/@app?format=json&fields=score
Response format
200 OK
{
"entry" : [
{
"score" : "76"
}
],
"itemsPerPage" : 1,
"totalResults" : 1
}
Deleting Appdata for a Specific Key
The following example shows how to delete Appdata for a specific key.
Request format
DELETE /api/restful/v1/appdata/@me/@self/@app?format=json&fields=score
Response format
202 Accepted
Reference Links
OpenSocial RESTful Protocol Specification v0.9 - 10. Messaging (Optional)
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
OAuth Request Body Hash 1.0 Draft 4
OAuth Consumer Request 1.0 Draft 1
Revision History
- 12/11/2012
- Initial release