People
people.get
This is an API for acquiring user profile information and user friend lists.
API definitions
| REST Base URI | http://app.mbga-platform.jp/social/api/restful/v2 ( Service ) http://app.sb.mbga-platform.jp/social/api/restful/v2 ( Sandbox ) |
| REST HTTP Method | GET |
| REST URI Fragment | ``` /people/{-list |
| REST Query Parameters | GetPerson-Request-Parameters GetPeople-Request-Parameters |
| Return Object | Person (in the case of either /people/{userId}/@self or /people/{userId}/@all/{personId}, /people/{userId}/@friends/{personId} ) Collection |
Approval
| type | permission | description |
|---|---|---|
| ANONYMOUS | false | Unauthorized access |
| SECURITY_TOKEN | false | Authorization using a security token |
| OAUTH_MOBILE | false | Authorization using an OAuth Token issued for a mobile device |
| OAUTH_CONSUMER | true | Authorization using a Consumer Request |
RESTful API response codes
| HTTP Status Code | HTTP Status Message | JSON-RPC Error Codes | Meaning |
|---|---|---|---|
| 200 | OK | – | Data successfully acquired |
| 400 | Bad Request | -32700, -32600, -32601, -32602, 400 | Corrupt request data on the client side |
| 401 | Unauthorized | 401 | Authorization error |
| 403 | Forbidden | 403 | The resource exists, but access is not possible due to a reason other than an authorization error. |
| 404 | Not Found | 404 | The resource doesn’t exist |
| 405 | Method Not Allowed | 405 | That operation is not allowed |
| 500 | Internal Server Error | -32603 | An error on the API server side |
| 503 | Service Unavailable | – | The API cannot be used temporarily |
JSON-RPC error codes
These are values are included in the code field of the Error object when an error has occurred.
| RPC Code | Meaning |
|---|---|
| -32700 (Parse error) | Invalid JSON format |
| -32600 (Invalid Request) | Invalid JSON-RPC request |
| -32601 (Method not found) | The method either doesn’t exist or is an unusable method |
| -32602 (Invalid params) | Invalid API request parameters |
| -32603 (Internal server error) | An error on the API server side |
| 400 (Bad Request) | A bad request on the client side that does not correspond to any other error |
| 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 |
| 405 (Method Not Allowed) | That operation is not allowed |
Data types
Get-Person-Request-Parameters
userId and groupId are specified as URI Template Parameters, and all other parameters are specified as Query Strings.
| Name | Type | Description |
|---|---|---|
| userId | UserId, Array | RequiredOnly '@all' is specifiable. The default is '@all'. |
| groupId | GroupId | Required |
| fields | Array | Optional |
Base data types
- Starndard-Request-Parameters
Get-People-Request-Parameters
userId, groupId, and personId are specified as URI Template Parameters, and all other parameters are specified as Query Strings.
| Name | Type | Description |
|---|---|---|
| userId | UserId, Array | *Required*Only '@all' is specifiable. The default is '@all'. |
| groupId | GroupId | Required |
| personId | UserId, Array | Optional |
| fields | Array | Optional |
Base data types
- Starndard-Request-Parameters
- Collection-Request-Parameters
Starndard-Request-Parameters
The following is a list of the supported fields.
| Name | Type | Description |
|---|---|---|
| format | String | *Optional*Only 'json' is specifiable |
See here for details.
Collection-Request-Parameters
The following is a list of the supported fields.
| Name | Type | Description |
|---|---|---|
| filterBy | String or Array | Optional, The specifiable fields are Person.id and Person.hasApp |
| filterOp | String or Array | Optional, equals is the only specifiable operator |
| filterValue | String or Array | Optional |
| count | Number | *Optional*An integer between 1 and 1000. The default value is 50. |
| sortBy | String | *Optional*Only 'id' is specifiable. |
| sortOrder | String | Optional 'ascending' or 'descending' |
| startIndex | Number | *Optional*An integer of 1 or greater |
See here for details.
Person
The following are the Person object fields stipulated in OpenSocial Social Data Specification 1.0.
| Name | Type | Description |
|---|---|---|
| id | UserId | The Person’s id value |
| nickname | String | The Person’s nickname |
| displayName | String | The Person’s display name (same value as Person.nickname) |
| aboutMe | String | Introduction text about the Person |
| birthday | Date | The Person’s birthday |
| interests | Array> | The Person’s interests |
| profileUrl | String | The URL of the Person’s profile (PC) |
| thumbnailUrl | String | The URL for the Person’s thumbnail (PC) |
| gender | String | The Person’s gender |
| hasApp | Boolean | Whether or not the Person has installed that application |
| age | Integer | The Person’s age |
| addresses | Array> | Where the Person lives (name of prefecture) |
The following are the fields that are unique to the Mobage open platform.
| Name | Type | Description |
|---|---|---|
| jobType | String | The Person’s occupation |
| bloodType | String | The Person’s blood type |
| isOwner | Boolean | Always false in the case of a Consumer Request |
| isViewer | Boolean | Always false in the case of a Consumer Request |
| isFamous | Boolean | Virtual user of a celebrity this flag is true |
| isVerified | Boolean | SMS Phone verification at account creation |
Precautions
- If the fields parameters are omitted, isOwner, isViewer, id, and nickname are selected. Even if these fields are not selected, they are included in the response.
Sample data
RESTful API
Acquiring user profile information
GET /social/api/restful/v2/people/10091/@self?fields=id,nickname,thumbnailUrl,profileUrl
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10091/1/xlarge-entire.gif",
"nickname" : "Midenhall",
"id" : "sb.mbga.jp:10091",
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10091"
}
Acquiring a list of the user’s friends
GET /social/api/restful/v2/people/10045/@friends?fields=id,nickname,thumbnailUrl,profileUrl
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"entry" : [
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10077/9/xlarge-entire.gif",
"nickname" : "Cannock",
"id" : "sb.mbga.jp:10077",
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10077"
},
{
"isOwner" : false,
"thumbnailUrl" : "http://sb.yahoo-mbga.jp/img_ava/profile/10093/12/xlarge-entire.gif",
"nickname" : "Moonbrooke",
"id" : "sb.mbga.jp:10093",
"isViewer" : false,
"profileUrl" : "http://sb.yahoo-mbga.jp/10093"
}
],
"startIndex" : 1,
"sorted" : false,
"updatedSince" : false,
"itemsPerPage" : 50,
"totalResults" : 2,
"filtered" : false
}
Determining whether or not the specified user is a friend
The following occurs if the user is a friend.
GET /social/api/restful/v2/people/10045/@friends/10093
Host: app.sb.mbga-platform.jp
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"isOwner" : false,
"nickname" : "Moonburg",
"id" : "sbdev.dena.jp:10093",
"isViewer" : false
}
404 Not Found is returned as follows if the user is not a friend.
GET /social/api/restful/v2/people/10045/@friends/10092
Host: app.sb.mbga-platform.jp
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"Error" : {
"Code" : "404",
"Message" : "Not Found"
}
}
See Also
OpenSocial Core API Server Specification 1.0
OpenSocial Core Data Specification 1.0
OpenSocial Social API Server Specification 1.0
OpenSocial Social Data Specification 1.0
Revision History
- 12/2010
- Initial Release.