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.

entry Field

Specify this as an array of AppdataEntry objects. The following can be defined as AppdataEntry object fields.

JSON Representations

The following representations are all handled as the same entity.
 
1. Full representation

  {
    "entry": [
      { "key": "score", "value": "78" },
      { "key": "high_score", "value": "97" }
    ]
  }

2. Simple representation of AppdataEntry only

  {
    "entry": [
      { "score": "78" },
      { "high_score": "97" }
    ]
  }

3. 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.

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.

appid

Only @app can be specified for the appid parameter.

Query Parameters

format

You can specify the response format as shown below.

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.

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

• 03/01/2013
  • Initial release