Guides:
Reference:
SDK Reference:
Tools:

API

Introduction

At GameStamper's core is the social graph; people and the connections they have to everything they care about. The Graph API presents a simple, consistent view of the GameStamper social graph, uniformly representing objects in the graph (e.g., people, photos, events, and pages) and the connections between them (e.g., friend relationships, shared content, and photo tags).

Every object in the social graph has a unique ID. You can access the properties of an object by requesting https://graph.gamestamper.com/ID. For example, the official page for the GameStamper Fan Page has id pg181036355272263, so you can fetch the object at https://graph.gamestamper.com/pg181036355272263:

{
 "name": "GameStamper",
 "type": "page",
 "link": "http://www.gamestamper.com/pg181036355272263",
 "username": "platform",
 "founded": "January 2011",
 "company_overview": "GameStamper Platform enables anyone to build...",
 "mission": "To make the web more open and social.",
 "products": "GameStamper Application Programming Interface (API)...",
 "fan_count": 449921,
 "id": "pg181036355272263",
 "category": "Technology"
}

Alternatively, people and pages with usernames can be accessed using their username as an ID. Since "pg181036355272263" is the username for the page above, https://graph.gamestamper.com/pg181036355272263 will return what you expect. All responses are JSON objects.

All objects in GameStamper can be accessed in the same way:

All of the objects in the GameStamper social graph are connected to each other via relationships. We call those relationships connections in our API. You can examine the connections between objects using the URL structure https://graph.gamestamper.com/ID/CONNECTION_TYPE. The connections supported for people and pages include:

All of the different types of objects and connections we support are included in the Graph API reference documentation.

Authorization

The Graph API as such allows you to easily access all public information about an object. For example, https://graph.gamestamper.com/100002241154490 (100002241154490) returns all the public information about 100002241154490. For example a user's first name and profile picture are publicly available.

To get additional information about a user, you must first get their permission. At a high level, you need to get an access token for the user. After you obtain the access token for the user, you can perform authorized requests on behalf of that user by including the access token in your Graph API requests:

https://graph.gamestamper.com/ID?access_token=...

For example https://graph.gamestamper.com/100002241154490 (100002241154490) returns additional information about 100002241154490.

The Graph API uses OAuth 2.0 for authorization. Please read the authentication and authorization guide which provides details of GameStamper's OAuth 2.0 implementation, how to request permissions from a user and obtain an access token.

Getting an access token for a user with no extended permissions allows you to access the information that the user has made available to everyone on GameStamper. If you need specific information about a user, like their email address or work history, you must ask for the specific extended permissions. You can learn about permissions you need, to access each property and connection of an object from the Graph API reference documentation.

Reading

The Graph API allows you to read properties and connections of the GameStamper social graph. You can use the API to read specific fields, get pictures of any object, introspect an object for metadata and get real-time updates on any changes.

Selection

By default, most object properties are returned when you make a query. You can choose the fields (or connections) you want returned with the "fields" query parameter. For example, this URL will only return the id, name, and picture of 100002241154490: https://graph.gamestamper.com/100002241154490?fields=id,name,picture

You can also request multiple objects in a single query using the "ids" query parameter. For example, the URL https://graph.gamestamper.com/?ids=100002241154490,100001294643267 returns profiles for 100002241154490 and 100001294643267 in the same response. The "ids" parameter accepts both comma-separated lists and json-encoded arrays.

Additionally, there is a special identifier me which refers to the current user. So the URL https://graph.gamestamper.com/me returns the active user's profile.

Pictures

You can render the current profile photo for any object by adding the suffix /picture to the object URL. For example, this will render your public profile photo:

<img src="https://graph.gamestamper.com/100002241154490/picture"/>

The same URL pattern works for all objects in the graph:

You can specify the picture size you want with the type argument, which should be one of square (50x50), small (50 pixels wide, variable height), and large (about 200 pixels wide, variable height): https://graph.gamestamper.com/100002241154490/picture?type=large.

Paging

When querying connections, there are several useful parameters that enable you to filter and page through connection data:

Introspection

The Graph API supports introspection of objects, which enables you to see all of the connections an object has without knowing its type ahead of time. To get this information, add metadata=1 to the object URL, and the resulting JSON will include a metadata property that lists all the supported connections for the given object. For example, you can see all the connections for 100002241154490 above by fetching https://graph.gamestamper.com/100002241154490?metadata=1. That outputs:

{
  "name": "100002241154490",
  "metadata": {
    "connections": {
        "feed": "https://graph.gamestamper.com/100002241154490/feed",
        "picture": "https://graph.gamestamper.com/100002241154490/picture"
    }
  }
}

The introspection feature is a useful and extensible way to find all the things your users are connected to.

Searching

You can search over all public objects in the social graph with https://graph.gamestamper.com/search. The format is:

https://graph.gamestamper.com/search?q=QUERY&type=OBJECT_TYPE

We support search for the following types of objects:

You can also search an individual user's News Feed, restricted to that user's friends, by adding a q argument to the home connection URL:

Publishing

You can publish to the GameStamper graph by issuing HTTP POST requests to the appropriate connection URLs, using an access token on behalf of the user. For example, you can post a new wall post on 100002241154490's wall by issuing a POST request to https://graph.gamestamper.com/100002241154490/feed:

curl -F 'access_token=...' \
	 -F 'message=Hello, Dev. I like this new API.' \
	 https://graph.gamestamper.com/100002241154490/feed

The Graph API reference provides more detailed information on the supported arguments and their corresponding values.

You can comment on a post by posting to https://graph.gamestamper.com/POST_ID/comments:

curl -F 'access_token=...' \
	 https://graph.gamestamper.com/313449204401/comments

Most write operations require extended permissions for the active user. See the authentication guide for details on how you can request extended permissions from the user during the authentication step.

We support writing the following types of objects:

Method Description Arguments
/PROFILE_ID/feed create a new post on the given profile's feed/wall message, picture, link, name, caption, description, source
/POST_ID/comments comment on the given post message
/PROFILE_ID/notes write a note on the given profile message, subject
/PROFILE_ID/albums create an album name, message
/ALBUM_ID/photos upload a photo to an album message

You can post to the authenticated user's feed or notes by issuing your request directly to /me/feed or, /me/notes, respectively. For example, this posts a message to the authenticated user's wall:

curl -F 'access_token=...' \
	 -F 'message=I am posting to my own feed. I am awesome.' \
	 https://graph.gamestamper.com/me/feed

Next Steps

All of the objects, connections, and operations supported by GameStamper are documented in the Graph API reference.