If unnecessary data is obtained when issuing requests to the API server, not only are server resources used wastefully, but the application response time slows down, which affects user operability.

This document presents guidelines for speeding up applications by preventing extremely wasteful requests from being issued.

If API requests from a partner are abnormally frequent or the method of issuing requests is considered to be inefficient, the partner may be directly requested to make improvements. Also, in an emergency situation, applications may be forced to switch to maintenance mode or API usage restrictions may be imposed. Thank you for your understanding.

Issuing Accesses Using @all or @friends in the People API

Since Mobage does not set an upper limit for the number of friends, some users have tens of thousands of friends. An API request to get a list of friends for this kind of user may take longer to execute than expected. You should consider the following methods to provide a service for getting a list of friends at any time.

1. Use a Message Queue or equivalent to pass the access token that is delivered from the Gadget Server to another system at such times as the user's first access and then perform the API access on the backend using the Proxy Model
2. Since API execution results are saved in a database for approximately 24 hours, reuse the saved data

An API access can obtain at most 1000 entries at a time. To get all the friends for this kind of user, execute the API until the following condition is satisfied.

startIndex x itemsPerPage > totalResults

When accessing the API multiple times, the access token delivered from the Gadget Server must be managed for each user with an expiration.

Using the count and fields Parameters to Explicitly Get the Required Data

The count and fields parameters can be used with GET type APIs. For example, if the only fields that are used in People API are id, nickname, thumbnailUrl, and profileUrl, and no more than 7 items are to be output per page, then specify the following.

fields
　　id,nickname,thumbnailUrl,profileUrl
count
　　7

In addition, if you want to extract only those users who have installed the application, use a filter and set hasApp to true.

• Request sample

GET /api/restful/v1/people/@me/@friends?count=7&fields=id%2Cnickname%2CthumbnailUrl%2CprofileUrl&format=json&filterBy=hasApp&filterOp=equals&filterValue=true
Host: sp.app.mbga.jp

• Response sample

200 OK
Content-Type: application/json

{
   "entry" : [
      {
         "nickname" : "OFFsuzuki",
         "thumbnailUrl" : "http://mbga.jp/img_u/10033/0.0.gif",
         "id" : "mbga.jp:10033",
         "profileUrl" : "http://mbga.jp/_u?u=10033"
      },
      {
         "nickname" : "e-maru",
         "thumbnailUrl" : "http://mbga.jp/img_u/10059/0.0.gif",
         "id" : "mbga.jp:10059",
         "profileUrl" : "http://mbga.jp/_u?u=10059"
      }
   ],
   "startIndex" : 1,
   "isSorted" : true,
   "itemsPerPage" : 7,
   "totalResults" : 2
}

In other words, for a GET type API, always consider the following when making the request.

• Use count to only obtain the number of items that you need
• Use fields to only obtain the attributes you need
• Use filter to only obtain the data that matches some desired condition
   

  Execution Frequencies for the Message and Activity APIs

  If a constraint is applied to the execution frequency of Message API or Activity API and the constraint is exceeded, 503 Service Unavailable will be returned.

Guidelines for constraints are summarized below.

With regard to constraints when using Proxy mode, large amounts of Message or Activity feeds should not be distributed to users. You should only apply constraints in the smallest but effective extent depending on the application. Also, if it is technically feasible, you should manage the above constraints in your application so that the API requests themselves are not sent. Finally, since you may wish to change the above constraints after studying the API load, be sure to implement them in a flexible way.

Although the Message API is distributed using the Trusted model (Consumer Request) and a request should be issued every four hours, you should set an appropriate interval (approximately 1 second) when sending requests. Even if accesses are performed in parallel, the API server could still lock out requests, so it may not be possible to achieve the expected speed and other applications might also be affected.

In summary, do the following with Activity/Message APIs.

• Avoid submitting unnecessary Activity/Message APIs as much as possible
• If possible, throttle API requests themselves in the application so that the constraints mentioned above are not exceeded
• Set an appropriate interval when sending requests without performing accesses in parallel for Message posts in Trusted (Consumer Request) mode
   

  API Response Cache

  To balance having to pass a content review, a content cache cannot be held on the partner side for the TextData API , but other GET type API responses that do not require timeliness may be cached for approximately 24 hours. For example, if user profiles or URLs of Avatar images are allowed during application execution, they should be actively cached.
   

  Acquiring Data Using the TextData API

  If a partner is going to use the TextData API, the TextData#id values should be saved in a database held by the partner.
  At the same time, corresponding TextData#status values should also be saved in a similar manner. You should also update the corresponding status value you have on hand when using PUT or DELETE in the TextData API.
  Although a value different from the corresponding status value may be returned at this time, since DeNA customer support considers this to be an inappropriate posting, the message "Deleted by the administrator" may be issued.

Also, when possible, you should specify ownerID or writerID when using POST. Try to design the application by using a combination of ownerID and writerID so that the minimum required data set will be created. Note that when filterBy is not used, processing could become extremely slow if a large amount of data is obtained by a GET access.

The TextData API can get collection resources using writerID and ownerID as conditions while sorting by id or updated values, and can get collections for which multiple ids are specified directly. Since these techniques are fairly intuitive and a quick response is normally expected, you should actively use these techniques.

• Request sample

GET /api/restful/v1/textdata/@app/comment/@all/1111;1112;1115?fields=id%2Cdata%2Cstatus%2Cpublished%2Cupdated%2CwriterId&format=json
Host: sp.app.mobage.kr

• Response sample

  200 OK
  Content-Type: application/json
  
  {
     "entry" : [
        {
           "writerId" : "mobage.ja:10062",
           "published" : "2010-01-21T14:39:19",
           "status" : "0",
           "id" : "1111",
           "data" : "My heart is beating wildly for online3",
           "updated" : "2010-01-21T14:39:19"
        },
        {
           "writerId" : "mobage.ja:10063",
           "published" : "2010-01-21T14:39:19",
           "status" : "0",
           "id" : "1112",
           "data" : "the closet series is more interesting",
           "updated" : "2010-01-21T14:39:19"
        },
        {
           "writerId" : "mobage.ja:10034",
           "published" : "2010-01-21T14:39:19",
           "status" : "0",
           "id" : "1115",
           "data" : "I enjoyed the update to 23 Slaves and me＾＾",
           "updated" : "2010-01-21T14:39:19"
        }
     ],
     "startIndex" : 1,
     "itemsPerPage" : 50,
     "totalResults" : 3
  }
  

Revision History

• 03/01/2013
  • Initial release