People
本文档无中文版本,
请查看其他语言。
Endpoint for Social API
Note: Social API includes Appdata API, Blacklist API, People API, Profanity API, Leaderboard API, Remote Notification API.
Mobage Simplified Chinese Platform
| Production Social | http://sp.mobage-platform.cn/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.cn/social/api/restful/v2 |
| Environment | URL |
| --- | --- |
Mobage Traditional Chinese Platform
| Environment | URL |
|---|---|
| Production Social | http://sp.mobage-platform.tw/social/api/restful/v2 |
| Sandbox Social | http://sp.sb.mobage-platform.tw/social/api/restful/v2 |
Data Type Definition
| Name | Type | Description | CN | JP | WW |
|---|---|---|---|---|---|
| id | UserId | The user's ID value | * | * | * |
| displayName | String | The user’s display name (same value as nickname) | * | * | * |
| aboutMe | String | Introduction text about the user | * | * | |
| addresses | Plural-Field<Address> | Where the user lives (name of prefecture) | * | * | |
| age | Number | The user’s age | * | * | * |
| birthday | Date | The user’s birthday | * | * | |
| gender | String | The user’s gender | * | * | |
| hasApp | Boolean | Whether or not the user has installed that application | * | * | * |
| interests | Plural-Field<string> | The user’s interests | * | * | |
| nickname | String | The user’s nickname | * | * | * |
| thumbnailUrl | String | The URL for the user’s thumbnail | * | * | * |
| jobType | String | The user’s occupation | * | * | |
| bloodType | String | The user’s blood type | * | * | |
| ageRestricted | Boolean | Whether or not the user has been restricted by age | * |
Description
This is an API for acquiring user profile information and user friend lists.
URI Fragment
/people/{-list|,|userId}/{groupId}
/people/{-list|,|userId}/{groupId}/{-list|,|personId}
Supported Formats
JSON
HTTP Method
GET
Request Parameters
| Name | Type | Required/Optional | Parameter | Description |
|---|---|---|---|---|
| userId | UserId, Array | Required | URI Template Parameters | @me or direct value |
| groupId | GroupId | Required | URI Template Parameters | The only legal values are @all, @self, or @friends. |
| personId | UserId, Array | Optional | URI Template Parameters | direct value |
| fields | Array | Optional | Query String | the names in the data type User for the CN platform |
| format | String | Optional | Query String | Only json is specifiable |
| filterBy | String or Array | Optional | Query String | The specifiable fields are id and hasApp |
| filterOp | String or Array | Optional | Query String | equals is the only specifiable operator |
| filterValue | String or Array | Optional | Query String | The values for filter keys. |
| count | Number | Optional | Query String | An integer between 1 and 1000. The default value is 50. |
| sortBy | String | Optional | Query String | Only id is specifiable. |
| sortOrder | String | Optional | Query String | ascending or descending |
| startIndex | Number | Optional | Query String | An integer of 1 or greater |
Request Headers
Any request to the Mobage REST APIs must include the Authorization header. For more details, see How to add the Authorization Header .
Request Body
None
Response Body
- User (in the case of either /people/{userId}/@self or /people/{userId}/@all/{personId}, /people/{userId}/@friends/{personId})
- Collection of Users (in all other cases)
Response Status Code
| HTTP Status Code | HTTP Status Message | Meaning |
|---|---|---|
| 200 | OK | Data successfully acquired |
| 400 | Bad Request | Corrupt request data on the client side |
| 401 | Unauthorized | Authorization error |
| 403 | Forbidden | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 404 | Not Found | The resource doesn’t exist |
| 500 | Internal Server Error | An error on the API server side |
| 503 | Service Unavailable | The API cannot be used temporarily |
Notes
If the fields parameters are omitted, the user's ID and nickname are selected. The user ID and nickname are returned in every response.
Example 1. Acquire User Profile Information
HTTP Request
GET /social/api/restful/v2/people/10091/@self?fields=id,nickname,thumbnailUrl
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"thumbnailUrl" : "http://sb.mbga-platform.jp/img_ava/profile/10091/1/xlarge-entire.gif",
"nickname" : "Midenhall",
"id" : "sb.mbga.jp:10091"
}
Example 2. Acquire a List of the User's Friends
HTTP Request
GET /social/api/restful/v2/people/10045/@friends?fields=id,nickname,thumbnailUrl
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"thumbnailUrl" : "http://sb.mbga-platform.jp/img_ava/profile/10077/9/xlarge-entire.gif",
"nickname" : "Cannock",
"id" : "sb.mbga.jp:10077"
},
{
"thumbnailUrl" : "http://sb.mbga-platform.jp/img_ava/profile/10093/12/xlarge-entire.gif",
"nickname" : "Moonbrooke",
"id" : "sb.mbga.jp:10093"
}
],
"startIndex" : 1,
"sorted" : false,
"updatedSince" : false,
"itemsPerPage" : 50,
"totalResults" : 2,
"filtered" : false
}
Example 3. Determining whether the Specified User is a Friend
HTTP Request
GET /social/api/restful/v2/people/10045/@friends/10093
Http Response is as follows if a specified user is a friend:
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"nickname" : "Moonburg",
"id" : "sb.mbga.jp:10093"
}
Http Response is as follows if the user is not a friend.
HTTP Response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"Error" : {
"Code" : "404",
"Message" : "Not Found"
}
}
Example 4. Verify the Current User
HTTP Request
Content-Type: application/json; charset=utf-8
Authorization: OAuth realm="", oauth_consumer_key="31816a6d9beac8c1xxxx", oauth_nonce="b9a19f5ceac92a7bxxxx", oauth_signature="yY0IRUStlDYw1qcyPuz8fsD%2BIrxxxx", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1331798387", oauth_token="sp_client_id%3A58cee178e5ea60732d2b6fae0294xxxx", oauth_version="1.0"
GET /social/api/restful/v2/people/@me/@self?fields=id,thumbnailUrl,hasApp,displayName,nickname
Host: sb.sp.mbga-platform.jp
Accept: application/json
HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"displayName": "username",
"hasApp": true,
"id": "10000",
"nickname": "username",
"thumbnailUrl": "http://sb-sp.mbga.jp/img_u/10000/111.1.png"
}
How to Add the Authorization Header
Step 1. Create the base string**
- build a string for OAuth parameters: firstly sort the following parameters alphabetically and URL encode the names and values, then join name and value with "=", finally join name/value pairs with "
&"
| Parameter | Description | Value |
|---|---|---|
oauth_consumer_key | The Consumer Key for the application | Issued when resist the application |
oauth_nonce | Unique value for each request | Generated on the game server |
oauth_signature_method | Hash method | Only HMAC-SHA1 is specifiable |
oauth_timestamp | UNIX timestamp | Generated on the game server |
oauth_token | The token code | oauth_token is obtained from the token credential. |
oauth_version | OAuth version | Only 1.0 |
- URL encode the following three parameters.
| Parameter | Description |
|---|---|
| Request Method | HTTP Method to the API Server |
| API URL | URL to the API Server (exclude query parameters) |
| OAuth Parameters | A string Built in previous step |
- join the encoded parameters with "&".
Step 2. Generate the oauth_signature
-
Build a secret by joining the Consumer Secret and the Token Secret (obtained from the token credential) with "
&". -
Pass the base string and secret to the HMAC-SHA1 hashing algorithm.
-
the output of HMAC-SHA1 hashing algorithm is a binary string. Use base64 encode to produce the signature string.
A tool is provided to verify whether your signature is correct. Refer to Oauth Signature Tool.
Step 3. Build the Authorization Header
Follow the steps to build the “Authorization” header:
-
URL encode the parameter names and values in the table below
-
Double quote the value, join name and value with "=", join name/value pairs with ","
-
Add realm parameter as an option
-
Add "OAuth " (including the space at the end) to the beginning of the header.
| Parameter | Value |
|---|---|
| oauth_consumer_key | Issued when resist the application |
| oauth_nonce | Generated on the game server |
| oauth_signature | Generated on the game server, Refer to Step 2. Generate the oauth_signature |
| oauth_signature_method | only "HMAC-SHA1" is specifiable |
| oauth_timestamp | Generated on the game server |
| oauth_token | oauth_token is obtained from the token credential. |
| oauth_version | Only 1.0 |
Authorization Header Example
OAuth realm="", oauth_consumer_key="195dcf3f2b64da74549f", oauth_nonce="abb5031d1d767d3626e4", oauth_signature="nzWySwCI9oIUU9mSTnIvrti7V7I%3D", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1363057344", oauth_token="sp_client_id%3A6317c85392724d8914904f708f16d01d", oauth_version="1.0"