Fortsätt till Netlog

sekunder till

Developer / Documentation / OpenSocial REST API

This is meant as a reference. See our openSocial tutorial for a more step-by-step approach.

The OpenSocial REST API allows a developer to retrieve pieces of information about a user and his friends by sending HTTP GET requests to our server.

In the other direction, you can also POST two types of messages back to Netlog:

  • Activities about the user that will show up in the logs of his friends:
    "Tom just received a gift from Bill!"
  • Notifications to the user notifying him of certain events within the application:
    "You just received a gift from Bill!"

First of all, you need to make yourself known to our REST server so it knows you and your relation to the people you want to retrieve information from.

Inside the gadget, you can retrieve the token by doing the following in javascript: 

 var token = shindig.auth.getSecurityToken();

Once you get the security-token, you can proceed on doing your requests.
An example of an URL fetching the friends of a specific user: 
 http://nl.api.netlog.com/opensocial/social/rest/people/31576831/@friends?st=NTVkYmIxYWI4NDcyYWZjMDJjMWI2NmY4MTEwMzE0OWU=

The default output format is JSON. However, if you specify format= in your query, the output will be returned in the desired format.

Our REST API is capable of returning the data in 3 kinds of formats:

  1. XML
  2. JSON
  3. ATOM

For a detailed explanation of what is possible, also see the openSocial RESTful protocol spec.

Some possible actions

Type URI Description
People: fetching information (GET request)
 
  1. /people/@me/@self
  2. /people/{guid}e/@self
  3. /people/{guid}/@friends
  1. Profile info for the person requesting the data
  2. Profile record for Netlog user {guid}
  3. Collection of all friends of user {guid}, a subset of @all

Only publicly available info about a person will be returned. To request specific fields other then the defaults of nickname, age, gender, etc... attach a fields=[comma-separated fields] parameter to the URL.
People: posting actions (POST request)
  We do not allow people-related actions (e.g. friendship request/remove ...) trough openSocial.
Fetching activities (GET request)
  1. /activities/{guid}/@self
  2. /activities/{guid}/@friends
  3. /activities/{guid}/@self/{activityid}
  1. Collection of activities generated by given user
  2. Collection of activities for friends of the given user {guid}
  3. Individual activity resource; usually discovered from collection
Posting activities and notifications (POST request)
We do not allow sending private messages or e-mails trough openSocial
  1. /activities/{guid}/@self/@app
  2. /messages/{guid}/@self
  1. Post activity about user {guid}
    (e.g. 'UserA just sent a gift!')
  2. Send notification to user {guid}
    (e.g. 'You have been challenged for a duel!')
The message should be sent as a json-encoded array in the POST body, as follows:
Activity:
{ "body ": "My activity body text ", "title ": " just posted an activity! "}
Notification:
{ "type " : "notification ", "title " : "requiredButWontShow ", "body " : "myNotifText ", "recipients " : [id1,id2...]}
Retrieving appdata (GET request)
  1. /appdata/{guid}/@self/{appid}
  2. /appdata/{guid}/@friends/{appid}
  3. /appdata/{guid}/@self/{appid}?fields=count
  1. All app data for user {guid}, app {appid}
  2. All app data for friends of user {guid} and app {appid}; read-only (only GET and HEAD supported)
  3. The count field for user {guid}, app {appid}
Note: you can request the value for oen or more specific keys by passing parameter 'fields' as follows: fields=key1,key2
Storing/updatig appdata (POST request)
  1. /appdata/{guid}/@self/{appid}
  1. App data for user {guid}, app id # {appid}
Note that app data should be sent as a JSON string in the POST body containing the key-value pair(s) you want to insert or update: { "myKey1" : "myValue1 ", "myKey2 " : "myValue2 "}

Possible query parameters when fetching data

(whenever relevant)
Parameter Description
count={value}

If you specify this parameter, our container will only return the x amount of results you want. If a request ends up generating 30 results, and you only want to retrieve 10 of them, use this parameter.
filterBy={value}

Returns items from a collection, filtered by the given field. We currently only support topFriends.
filterOp={value}

The operation to use when filtering a collection. At this time we only support "contains"
filterValue={value}

The value to use when filtering a collection.
format={value}

Format desired. Pick between ATOM, JSON or XML. Default is JSON if not provided.
fields={value}

List of the fields you want to include in the resultset. If no fields are provided, we will return the userid and profileUrl. If you want to specify multiple fields, please a comma as delimiter.

  • id
  • age
  • thumbnailUrl
  • profileUrl
  • birthday
  • gender
  • interests
  • languagesSpoken
  • relationshipStatus
  • sexualOrientation
  • tags
  • networkPresence
  • aboutMe
  • nickname
  • displayName
  • addresses
  • jobs
  • photos
  • lookingFor
  • music
  • schools
  • urls
Example:
 http://nl.api.netlog.com/opensocial/social/rest/people/
userid/@friends?st=ST=&fields=status,thumbnailUrl
sortBy={value}

For a collection, return entries sorted by the given field. Currently we only support sorting by displayName and topFriends.
sortOrder={value}

Can either be "ascending" or "descending", defaults to ascending. Used to sort objects in a collection.
startIndex={value}

Starts displaying the results starting from startIndex. For example, if the request returns 30 items, but you only want the last 10, you would specify a startIndex of 20.

Some examples


Fetch information about myself (GET). 
 http://nl.api.netlog.com/opensocial/social/rest/people/@me/@self?st=OTI3MTM3ODdjNTgwMjJlOGE0MGFiZDc4OTllMzM3MzI=&fields=id,status,thumbnailUrl

Will fetch info about the requester (the logged in user).
Will only return the fields id, status and thumbnailUrl.

Fetch information about my friends (GET). 
 http://nl.api.netlog.com/opensocial/social/rest/people/@me/@friends?st=OTI3MTM3ODdjNTgwMjJlOGE0MGFiZDc4OTllMzM3MzI=&fields=profileUrl,displayName

Will fetch info about the friends of the requester (the logged in user).
Will only return the fields profileUrl and displayName.

Fetch all activities created by a user (GET). 
 http://nl.api.netlog.com/opensocial/social/rest/activities/57854631/@self?st=NTQyZWY0NDAyNGE2OTQ4ZDc5NWUwY2I1OWM5NzAwZDg=

Will return all the activities (20 items per page default) for the given user (user with userId 57854631 in this example).

Post an activity for a user (POST). 
 http://nl.api.netlog.com/opensocial/social/rest/activities/57854631/@self?st=NTQyZWY0NDAyNGE2OTQ4ZDc5NWUwY2I1OWM5NzAwZDg=
 POSTbody: { "title" : "sneezed!", "body" : "Bless him."}

Will post an activity log to all friends of the given user (about user with userId 57854631 and text 'UserName sneezed!' in this example).

Post a notification for a user (POST). 
 http://nl.api.netlog.com/opensocial/social/rest/messages/57854631/@self?st=NTQyZWY0NDAyNGE2OTQ4ZDc5NWUwY2I1OWM5NzAwZDg=
 POSTbody: {"type" : "notification", "title" : "requiredButWontShow", "body" : "hi!", "recipients" : [57854631]}

Will post a clickable notification to the given user (with userId 57854631 and text 'hi!' in this example).

Should you require more information about REST in OpenSocial, please visit the official REST documentation

Articles for app developers

Must-reads: Tutorials: creating apps with JS and PHP Netlog-specific: