Ning Developer Documentation

Skip to Content »

Ning Home

 

Warning: PHP Startup: failed to open stream: No such file or directory in /apps/B/7D4/51F/documentation/sections/rest/jsonoperations.php on line 2

Warning: PHP Startup: Failed opening '../301ify.php' for inclusion (include_path='.:/php/includes/XN:/php/includes/PEAR:/php/includes/other') in /apps/B/7D4/51F/documentation/sections/rest/jsonoperations.php on line 2

Ning Developer Documentation / REST API / JSON Operations

Ning REST API JSON-Format Operations

This document covers all Ning REST API operations that take traditional CGI key/value pairs and return JSON data. The relative URLs for these operation endpoints uniformly begin with /xn/rest/. Note that there are also REST API operations which use XML-formatted data and have endpoint URLs that specify /xn/atom/ ; the documentation for these can be found on the XML-Format Operations page.

Authentication

Any operation that creates, updates, or deletes data can only be performed by the owner of the target app. In order to authenticate the operation, a valid Ning authentication cookie (obtained through Ning sign-in) must be passed. (This is because the primary targeted usage of the JSON API is browser scripting. At present Ning does not support traditional HTTP authentication for JSON-format operations)

For GET operations which do not need to be authenticated, unencrypted HTTP can be used. Include the parameter xn_auth=no in the query string to circumvent Ning's authentication system and make an anonymous request.

Error Responses

For responses that indicate an error, Ning returns a JSON structure with a body that contains a plaintext English description of the error. (This may change in the future to provide more structured error responses.)

Here is a sample error structure:

{"errors":[{"error":"Unable to complete API call"}]}

Profiles

The profile object for a specified Ning user can be fetched with a GET query and updated with a PUT action. Here is a sample GET URL - note that the ID of the user is specified after the colon.

http://appname.ning.com/xn/rest/1.0/profile:david

And response to the above:

{"profile":
	{"gender":"m",
	"country":"US",
	"developer":"true",
	"fullName":"David Sklar",
	"description":"I'm a software architect at Ning and a swell guy.",
	"photoUrl":"http:\/\/api.ning.com\/icons\/profile\/8?default=4482",
	"location":"New York, NY",
	"profileUrl":"http:\/\/browse.ning.com\/any\/david",
	"zipcode":"10040",
	"relationship":
		{"pending":"true",
		"description":"pending"},
	"id":"david"}
}

The following table describes the parameters, whether they are available in results received through GET and whether they can be supplied in PUT actions. Note: When supplying these parameters in a PUT action, the property name should be prepended with the string profile_ - e.g. profile_country=US

Property Name Operation Usage Notes
birthDate.day GET and PUT Number from 1 to 31
birthDate.month GET and PUT Number from 1 to 12
birthDate.year GET and PUT Four-digit year
country GET and PUT Two-letter country code
description GET and PUT User-supplied profile description
developer GET and PUT Boolean value showing whether user has self-identified as a developer
email PUT only User's registered email address
fullName GET and PUT
gender GET and PUT
location GET and PUT City and district
photo PUT only If sent, the encoding for the PUT operation must be mime/multipart
photoUrl GET only URL of the user's photo image
profileUrl GET only URL of the user's profile page
relationship GET only Nested structure showing relationship between this user and the user who issued the query, if identifiable; see below for more details
zipcode GET and PUT Currently only takes US numeric zipcodes

Applications

The metadata for a specified Ning App can be fetched with a GET query and updated with a PUT action. A new App can also be cloned through a POST operation (an application_parent value must be supplied). Here is a sample GET URL - note that the ID of the App is specified after the colon.

http://appname.ning.com/xn/rest/1.0/application:cuteoverload

And response to the above:

{"application":
	{"createdDate":"2006-01-24T17:11:37.334Z",
	"iconUrl":"http:\/\/api.ning.com\/icons\/appatar\/7960?default=5331",
	"owner":"mfrost",
	"premium":true,
	"id":"CuteOverload",
	"viewSourceUrl":"http:\/\/www.ning.com\/view-source.html?appUrl=CuteOverload",
	"domains":[],
	"privateSource":true,
	"description":null,
	"tags":"adorable, anerable, cuteoverload, kittens, ehn, ahn!, puppies, cute, prosh",
	"online":true,
	"url":"http:\/\/cuteoverload.ning.com\/",
	"name":"What's Cuter?"}
}

The following table describes the parameters, whether they are available in results received through GET and whether they can be supplied in PUT actions. Note: When supplying these parameters in a PUT or POST action, the property name should be prepended with the string application_ - e.g. application_name=Frogs%20Ahoy

Property Name Operation Usage Notes
createdDate GET only ISO format
description GET, PUT, POST Currently unused
domains GET only Additional domains mapped using the domain-mapping premium service
icon PUT and POST only If sent, the encoding for the operation must be mime/multipart
iconUrl GET only URL of the icon image
id GET and POST only App ID used in the App's .ning.com hostname
name GET, POST, PUT App name used in info pages and search results
online GET, POST, PUT Boolean
owner GET only The user ID of the App owner
premium GET only Boolean indicating whether premium services have been purchased
privateSource GET only Boolean indicating whether the "hide source code" premium service has been purchased
tags GET, POST, PUT Comma-separated string of tag words
url GET only The URL of the App
viewSourceUrl GET only URL to view the App's source code

Contacts and Relationships

The Ning REST API includes powerful functions for both querying and manipulating users' friend and contact lists. Contact relationships can be queried individually or in bulk (through GET), and can be both created (through POST) and updated (through PUT).

Here's an example of querying a single relationship:

http://appname.ning.com/xn/rest/1.0/profile:tim/contact:brianm

The following contact object is returned:

{"contact":
	{"createdDate":"2006-06-19T01:42:14.456Z",
	"updatedDate":"2006-06-19T01:42:14.456Z",
	"contactRelationship":"contact",
	"email":"brianm@apac...",
	"screenName":"brianm",
	"photoUrl":"http:\/\/api.ning.com\/icons\/profile\/920?default=4529",
	"profileUrl":"http:\/\/browse.ning.com\/any\/brianm",
	"name":"Brian McCallister",
	"id":"brianm",
	"relationship":
		{"pending":"true",
		"description":"pending"}
	}
}

Friend list data can also be fetched in bulk:

http://appname.ning.com/xn/rest/1.0/profile:tim/contact(relationship='friend')&begin=0&end=5

The above query will return up to five of Tim's mutual friends. (The begin and end arguments are optional.)

These are the possible values for the relationship attribute, where the profile user is the owner of the friend list being queried, and the contact user is the user whose details have been returned in results:

Value Definition
blocked The contact user is blocked from communicating with the profile user
contact The contact user's details have been imported by the profile user
friend A mutually-confirmed friend relationship between both users
groupie The contact user has made an unconfirmed friend request to the profile user, and the contact user is not in the profile user's contact list
pending The profile user has made an unconfirmed friend request to the contact user
requested The contact user has made an unconfirmed friend request to the profile user, and the contact user is in the profile user's contact list

Relationships can be created or updated by POST or PUT. An example, with URL and POSTed data separated:

http://appname.ning.com/xn/rest/1.0/profile:tim/contact
contact_id=brianm&contact_relationship=friend

Possible values for contact_relationship are friend (which sends a friend request to the contact), not-friend (which denies a pending friend request from the contact) and block (which blocks communication from the contact).

Messaging

User-to-user messages can be sent by a POST operation. An example:

http://appname.ning.com/xn/rest/1.0/messaging
message_subject=Yeah+Yoz&message_body=Yoz+had+a+baby!&message.saveACopy=true
&message_to=Steve<steve>&message_to=<yoz>
&message_to=Timmy+Two+Thumbs<tim@ninginc.com>
Attribute Definition
message_body The main text of the message
message_saveACopy Boolean, whether to save a copy of the message in the sending user's mailbox
message_subject The message's subject line
message_to Message recipient, can be specified multiple times. The recipient's user ID or email address should be placed between angle brackets, optionally preceded by a name. (Email address is used to look up the user on Ning, not to send via email)