Skip to main content

TextData

Overview​

The TextData API gets and saves arbitrary text input from the user. Saved text is subject to monitoring. A TextDataGroup object that groups together TextData objects must first be created via the API using the Trusted Model (OAuth Consumer Request).


TextData Object Fields​

ValueDescriptionTypeNamespaceRemark
idid of the TextData objectxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
groupNamename of the TextDataGroup objectxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
parentIdID of the TextData object corresponding to the parentxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
writerIdguid of the person who wrote the dataxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
ownerIdguid of the owner of the dataxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
dataThe text dataxs:stringhttp://ns.dena.jp/mbga/gameapi/v1Maximum 2048 bytes
statusLogical status valuexs:inthttp://ns.dena.jp/mbga/gameapi/v1–
publishedCreation date and timexs:dateTimehttp://ns.dena.jp/mbga/gameapi/v1GMT
updatedModification date and timexs:dateTimehttp://ns.dena.jp/mbga/gameapi/v1GMT
note

There is no timezone specifier in the xsd:dateTime type in the response from the API. Therefore, it is represented in GMT (Greenwich Mean Time).

TextData#status Field Values​

statusDescription
0Normal
11Edited by user
21Edited by operator
31Edited by partner

TextDataGroup Object Fields​

ValueDescriptionTypeNamespaceRemark
idid of the TextDataGroup objectxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
nameName of the TextDataGroup objectxs:stringhttp://ns.dena.jp/mbga/gameapi/v1Maximum 32 bytes
appIdApplication idxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–
parentIdID of the TextDataGroup object corresponding to the parentxs:stringhttp://ns.dena.jp/mbga/gameapi/v1–

API Request​

HTTP Methods​

Proxy model

  • GET
    • Get a list of text data entries
    • Get text data
  • POST
    • Create text data
  • PUT
    • Update text data
  • DELETE
    • Delete text data

Trusted model

  • GET
    • Get a list of text data groups
    • Get a text data group
    • Get a list of text data entries
    • Get text data
  • POST
    • Create a text data group
    • Create text data
  • PUT
    • Update text data
  • DELETE
    • Delete a text data group
    • Delete text data

Endpoint URL​

  • Sandbox environment

    http://sb.sp.app.mbga.jp/api/restful/v1/textdata/{appid}/{gid}{-prefix|/|selector}
  • Production environment

    http://sp.app.mbga.jp/api/restful/v1/textdata/{appid}/{gid}{-prefix|/|selector}

URI Template Parameters​

appid​

Specify the following value for the appid parameter.

ValueDescriptionRemark
@appapplication id of the application currently being executedRequired
gid​

Specify one of the following values for the guid parameter.

ValueDescriptionRemark
@allRepresents the entire text data groupOptional
{gid}Specifies a gid (value of TextDataGroup.name field) used to categorize the text data. Forms the collection resource representing the list of text data entries.Optional
selector​

Specify one of the following values for the selector parameter.

ValueDescriptionRemark
@selfIndicates the specified text data group entryOptional
@allIndicates the text data collection that belongs to the specified text data group.Optional
@all/{-join;textDataId}

For {textDataId}, you can obtain a TextData collection resource by specifying multiple TextData#ids separated by semicolons.


Query Parameters​

The following query parameters can be specified.

format​

The response format is as shown below.

ValueDescriptionRemark
json"application/json; charset=utf8"Optional, default value

fields​

The fields below can be used to specify the TextData information that you wish to obtain. For the fields that can be specified, please see the description of the TextData object field.
To specify multiple fields, separate them with commas without any spaces in between.
If you omit the fields parameter, all of the attributes listed below are obtained.

In the interest of performance, you should only get the attributes that you need.

count​

When getting a response as a collection resource, you can use the count field to specify the maximum number of entries to obtain. The count field can be used when @all is specified for selector or when more than one TextData#ids is specified.

count can be a maximum of 1000, with a default value of 50.

In the interest of performance, you should only get the entries that you need.

startIndex​

For startIndex, specify the starting value of the collection resource. If startindex is omitted, 1 is assumed. When getting a TextDataGroup collection resource, the startIndex specification is ignored, and 1 is used.

filterBy​

You can only use filterBy when getting a TextData collection.

By using filterBy, you can add a search condition for the collection of TextData objects that will be returned in the response. For the filterBy value, specify a field that will be used as the search condition key.

The values of filterBy that can currently be specified are shown below.

filterByDescription
ownerIdTextData#ownerId
writerIdTextData#writerId

When filterBy is specified, filterOp and filterValue must also be specified.
Also, if ownerId and writerID are both used, they must be separated by a comma.
 
For example, to apply a filter in which both ownerId (guid: 5) and writerId (guid: 10) are specified, issue the following request.

GET /api/restful/textdata/@app/messageboard/@all?count=10&startIndex=11&filterBy=ownerId,writerId&filterOp=equals,equals&filterValue=5,10

filterOp​

You can only use filterOp when getting a TextData collection.

By using filterOp, you can add a search condition for the collection of TextData objects that are returned in the response. The filterOp value indicates how the search condition key and value should be evaluated.

The filterOp values that can currently be specified are shown below.

filterOpDescription
equalsThe field specified by filterBy must match the value specified by filterValue

When filterOp is specified, filterBy and filterValue must also be specified.
The number of fields specified for filterBy must be the same as the number of values of filterOp, separated by commas.

filterValue​

You can only use filterValue when getting a TextData collection.

By using filterValue, you can add a search condition for the collection of TextData objects that are returned in the response. filterValue indicates the value to be used when evaluating the search condition key.

The values of filterValue that can currently be specified are shown below.

filterValueDescription
{guid}guid value (integer)

When filterValue is specified, filterBy and filterOp must also be specified.
The number of fields specified for filterBy must be the same as the number of values of filterValue, separated by commas.

sortBy​

You can only use sortBy when getting a TextData collection.

sortBy and sortOrder can be specified to add a sort condition for the collection of TextData objects that are returned in the response. You can specify the field that is used for the sort key with the sortBy value.

The values of sortBy that can currently be specified are shown below.

sortByDescription
idTextData id
updatedTextData update date and time

When sortBy is specified, sortOrder must also be specified.

sortOrder​

You can only use sortOrder when getting a TextData collection.

By using sortBy and sortOrder, you can add a sort condition for the collection of TextData objects that are returned in the response. You can specify the sortOrder as ascending or descending.

The values of sortOrder that can currently be specified are shown below.

sortOrderDescription
ascendingAscending order
descendingDescending order

When sortOrder is specified, sortBy must also be specified.


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
viewer guid (opensocial_viewer_id value sent from the Gadget Server)
Trusted mode
application id issued on the Developer Site.

For more information about generating the OAuth Signature in Trusted mode, please see OAuth Consumer Request 1.0 Draft 1.


API Response​

Response Codes​

The following is a list of the API response codes.

Request HTTP methodResponse codeResponse messageDescription
GET200OKThe data was acquired successfully
POST201CreatedThe data was created successfully
PUT/DELETE202AcceptedThe data was updated or deleted successfully
GET/PUT/DELETE404Not FoundThe data does not exist or was physically removed
GET/PUT/DELETE403ForbiddenAccess failed for some reason other than an authentication error
GET/POST/PUT/DELETE400Bad RequestInvalid request data
GET/POST/PUT/DELETE401Unauthorized0Auth authorization failed
GET/POST/PUT/DELETE405Method Not AllowedMethod is not allowed
GET/POST/PUT/DELETE500Internal Server ErrorRequest failed because of an internal API problem

Processing Flow​

Please see the following samples for examples of the request and response formats used for each feature.

  1. The partner creates a new TextDataGroup. (Trusted)
  2. The following functions can be used with the new TextDataGroup. (Trusted)
  • Get TextDataGroup

  • Delete TextDataGroup
    3. Create a TextData entry that belongs to the TextDataGroup. (Trusted/Proxy)
    4. The following functions can be used with the new TextData entry. (Trusted/Proxy)

  • Get TextData

  • Update TextData

  • Delete TextData
     


    Notes​

  • Manage the TextDataGroup by accessing the API with the Trusted Model (OAuth Consumer Request)

  • You can only use alphanumeric characters and the underscore in the TextDataGroup#name value.

  • To represent a parent-child relationship for TextDataGroup#parentId and TextData#parentId, enter the id value of the parent as seen from the child. Since it is required for monitoring, be sure to nter this for data structures have parent-child relationships.

  • In the TextData#data field, enter a string that can be recognized as text. Note that if the text cannot be recognized, it may be deleted by the operator.

  • The addition or updating of a TextData entry when the TextData#data field contains forbidden words that are in violation of Mobage management policy will result in a 400 Bad Request status being returned.

  • The guid of the user who wrote the text data is?entered for TextData#writerId. If the numeric part of the guid is 0, the data is handled by the partner as update data according to the Trusted Model.

  • The partner should control the management of permissions for TextData when a user with a different guid than TextData#writerID tries to update the data. The API will update the text data even if the guid is different from TextData#writerId.

    • For example, in cases when the text data is used for a WiKi-like format, it is easy to see how multiple people will update the same data.
  • TextData#ownerId is a field that is provided for representing the original owner or the owner of the parent data. Be sure to set this field for an entry for the owner or for an entry with the Trusted Model.

    • For example, when a user can write to the message boards assigned to all the other users, the owner will be the user who owns the message board, so set the owner's ID for TextData#ownerId.
  • If the user indicated by TextData#ownerId user registered the viewer in a blacklist, use the BlackList API to prevent the viewer from being able to write.

  • Set the size of TextData#data so that it does not exceed 2048 bytes.

  • For a GET in which multiple TextData#ids are specified, specify only ids that are in the same group. You cannot get ids that belong to different groups.

  • Deleted TextData entries can no longer be obtained using GET. (404 Not Found will be returned)

  • If the user has not installed the corresponding application, 403 will be returned for the response code.

  • If the ownerID and parentID are not included in a POST request, 0 will be returned for the initial value.

    Restrictions​

  • Five TextDataGroups can be created per application.

  • The maximum number of entries that can be stored in each TextDataGroup is 100,000 if no more than 10,000 users have installed the application.

    • If the number of users who have installed the application up to the previous day is more than 10,000, then the maximum number of entries will be increased to 10 times the total number of users who have installed the application up to the previous day.
  • If the maximum number of entries is exceeded, entries will be physically deleted as needed beginning with the oldest entry among the entries in that group, (404 Not Found will be returned)

  • Do not manage TextData entries that belong to multiple categories with one TextDataGroup ID. (For example, set individual TextDataGroup IDs for postings with the "Greetings" feature and for postings with the "Strategy meeting" feature. However, one TextDataGroup ID should be used, for example, to enter entries in separate columns for "Title" and "Strategy description" on the "Strategy meeting" posting form.

  • Unicode 6.0 (iOS mobile device emoji) is not supported. UTF-8 is used as the character encoding for both input and output.

    Examples​

    Adding a TextDataGroup​

    This example shows how to add a new TextDataGroup.

Request Format​

POST /api/restful/v1/textdata/@app/@all
Content-Type: application/json; charset=utf8

{
"name": "diary"
}

Response Format​

201 Created

Deleting a TextDataGroup​

Request Format​

DELETE /api/restful/v1/textdata/@app/diary/@self

Response Format​

202 Accepted

Getting a TextDataGroup Collection​

This example shows how to use the count and startIndex query parameters with a TextDataGroup collection.

Request Format​

GET /api/restful/v1/textdata/@app/@all?count=2&startIndex=1

Response Format​

{
"entry" : [
{
"parentId" : "0",
"appId" : "12000002",
"name" : "diary",
"id" : "1"
},
{
"parentId" : "0",
"appId" : "12000002",
"name" : "bbs",
"id" : "2"
}
],
"startIndex" : 1,
"itemsPerPage" : 2,
"totalResults" : 5
}

Getting a TextDataGroup​

Reques? Format​

GET /api/restful/v1/textdata/@app/diary/@self

Response Format​

200 OK
Content-Type: application/json; charset=utf8

{
"startIndex" : 1,
"textDataGroup" : {
"parentId" : "0",
"appId" : "12000002",
"name" : "diary",
"id" : "1"
},
"itemsPerPage" : 1,
"totalResults" : 1
}

Getting a TextData Collection from a Group​

Request Format​

GET /api/restful/v1/textdata/@app/diary/@all?count=5&fields=id,data

Response Format​

{
"entry" : [
{
"id" : "1",
"data" : "Today's dinner"
},
{
"id" : "2",
"data" : "Milasista was seized"
},
{
"id" : "3",
"data" : "Montra is interesting"
},
{
"id" : "4",
"data" : "Nunuemba's image is a surprise!! !"
},
{
"id" : "5",
"data" : "I tried Burst luck"
}
],
"startIndex" : 1,
"itemsPerPage" : 5,
"totalResults" : 8
}

Getting a TextData Entry by Specifying Multiple TextData#ids​

Request Format​

GET /api/restful/v1/textdata/@app/messages/@all/100;1107;1108?format=json

Response Format​

{
"entry" : [
{
"status" : "0",
"data" : "I did infinite 1up",
"writerId" : "sb.sp.app.mbga.jp:10001",
"published" : "2010-01-19T06:29:57",
"parentId" : "0",
"id" : "1107",
"updated" : "2010-01-19T06:29:57",
"groupName":" messages",
"ownerId" : "sb.sp.app.mbga.jp:0"
},
{
"status" : "0",
"data" : "I want to jump the pole!" ,
"writerId" : "sb.sp.app.mbga.jp:12003",
"published" : "2010-01-19T06:30:03",
"parentId" : "0",
"id" : "1108",
"updated" : "2010-01-19T06:30:03",
"groupName":" messages",
"ownerId" : "sb.sp.app.mbga.jp:0"
}
],
"startIndex" : 1,
"itemsPerPage" : 50,
"totalResults" : 2
}

Creating a TextData Entry​

This example adds a new TextData entry to the diary TextDataGroup.
Example) User 10009 writes in the application's diary

Request Format​

POST /api/restful/v1/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8

{
"data" : "I'm also playing Kaito Royale"
}

Response Format​

201 Created
Location: http://sb.sp.app.mbga.jp/api/restful/v1/textdata/@app/diary/@all/19

{
"startIndex" : 1,
"textData" : {
"published" : "2009-12-09T06:39:01",
"writerId" : "10009",
"updated" : "2009-12-09T06:39:01",
"id" : "19",
"groupName" : "diary",
"data" : "I'm also playing Kaito Royale"
},
"itemsPerPage" : 1,
"totalResults" : 1
}

Example) User 10012 commented on user 10009's diary entry

Request Format​

POST /api/restful/v1/textdata/@app/diary/@all
Content-Type: application/json; charset=utf8

{
"data" : "I'm also doing that!",
"ownerId" : "10009"
}

Response Format​

201 Created
Location: http://sb.sp.app.mbga.jp/api/restful/v1/textdata/@app/diary/@all/44

{
"startIndex" : 1,
"textData" : {
"published" : "2009-12-09T08:42:23",
"writerId" : "sb.sp.app.mbga.jp:10012",
"updated" : "2009-12-09T08:42:23",
"id" : "44",
"parentId" : "19",
"groupName" : "diary",
"data" : "I'm also doing that!",
"ownerId" : "sb.sp.app.mbga.jp:10009"
},
"itemsPerPage" : 1,
"totalResults" : 1
}

Creating a TextData Entry​

Request Format​

GET /api/restful/v1/textdata/@app/diary/@all/5

Response Format​

{
"startIndex" : 1,
"itemsPerPage" : 1,
"textData" : {
"status": 0,
"data" : "I tried burst luck",
"writerId" : "sp.sb.app.mobage.kr:10012",
"published":" 2009-11-26T12:59:29",
"parentId" : "0",
"id" : "5",
"updated" : "2009-11-26T12:59:29",
"groupName" : "diary",
"ownerId" : "sp.sb.app.mobage.kr:0"
},
"totalResults" : 1
}

Updating a TextData Entry​

Request Format​

PUT /api/restful/v1/textdata/@app/diary/@all/5
Content-Type: application/json; charset=utf8

{
"data" : "I reached Lv30"
}

Response Format​

202 Accepted

Deleting a TextData Entry​

Request Format​

DELETE /api/restful/v1/textdata/@app/diary/@all/5

Response Format​

404 Not Found

Reference Material​

XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03

Revision History​

  • 12/11/2012
    • Initial release
  • Overview
  • TextData Object Fields
    • TextData#status Field Values
  • TextDataGroup Object Fields
  • API Request
    • HTTP Methods
    • Endpoint URL
    • Query Parameters
    • OAuth Signed Request
  • API Response
    • Response Codes
  • Processing Flow
    • Notes
  • Restrictions
  • Examples
    • Adding a TextDataGroup
    • Deleting a TextDataGroup
    • Getting a TextDataGroup Collection
    • Getting a TextDataGroup
    • Getting a TextData Collection from a Group
    • Getting a TextData Entry by Specifying Multiple TextData#ids
    • Creating a TextData Entry
    • Creating a TextData Entry
    • Updating a TextData Entry
    • Deleting a TextData Entry
  • Reference Material
  • Revision History