Skip to main content

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.

ValueDescriptionTypeNamespaceRemarks
person_idguid denoting persistent data ownerxs:stringhttp://ns.opensocial.org/2008/opensocial–
entryPersistent datatnx:AppdataEntry (unbounded)http://ns.opensocial.org/2008/opensocialCollection in key-value format

entry Field​

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

ValueDescriptionTypeNamespaceRemarks
keyPersistent data keyxs:stringhttp://ns.opensocial.org/2008/opensocialMaximum 32 bytes
valuePersistent data valuexs:stringhttp://ns.opensocial.org/2008/opensocialMaximum 1024 bytes

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" }
]
}
  1. Simple representation of AppdataEntry only
{
"entry": [
{ "score": "78" },
{ "high_score": "97" }
]
}
  1. 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.

ValueDescriptionRemark
@meguid of the viewerRequired
{guid}User IDRequired

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.

ValueDescriptionRemark
@selfRepresents an Appdata collection resource of the viewerRequired
appid​

Only @app can be specified for the appid parameter.

ValueDescriptionRemark
@appRepresents an Appdata entry resource for the application that is currently being executedRequired

Query Parameters​

format​

You can specify the response format as shown below.

ValueDescriptionRemark
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 methodResponse codeResponse messageDescription
GET200OKAppdata was successfully obtained
POST/PUT/DELETE202AcceptedAppdata was successfully created, updated or deleted
GET/POST/PUT/DELETE400Bad RequestInvalid request data
GET/POST/PUT/DELETE401Unauthorized0Auth authorization failed
GET/POST/PUT/DELETE403ForbiddenCould not access data for some reason other than because of an authentication error
GET/POST/PUT/DELETE405Method Not AllowedMethod is not allowed
GET/POST/PUT/DELETE500Internal Server ErrorRequest 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

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
  • Overview
  • Appdata Object Fields
    • entry Field
    • JSON Representations
  • API Request
    • HTTP Methods
    • Endpoint URL
    • Query Parameters
    • OAuth Signed Request
  • API Response
    • Response Codes
    • Notes
  • Examples
    • Creating Appdata
    • Getting Appdata for a Specific key
    • Deleting Appdata for a Specific Key
  • Reference Links
  • Revision History