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

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

TextDataGroup Object Fields

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.

gid

Specify one of the following values for the guid parameter.

selector

Specify one of the following values for the selector parameter.

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.

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.

 
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.

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.

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.

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.

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.

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

• 03/01/2013
  • Initial release