Request Overview

Rate Limits

The Ning API has a throttle rate of 20 requests per second, per Ning Network. When requests go over this limit, the API will return a 503 HTTP response.

Resource URL structure

A typical resource URL looks like:

http://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost/recent

A resource URL consists of several parts:

Ning API Domain http://external.ningapis.com
The base URL for the Ning API
Namespace Prefix /xn/rest
This defines that we are using the Ning API.
Ning Subdomain /apiexample
Specifies the Ning Ning Network that we are making requests to. You must use the Ning subdomain, you cannot use a custom domain.
API Version /1.0
Currently Ning is on version 1.0 of it’s Ning API and doesn’t support any other version.
Resource Type /BlogPost
The data we are working with.
Sort Ordering /recent
The order to return the results. This is an optional in the URL. Requests without a sort order do not guarantee any sort order. Sort order only applies to GET requests and recent is the only supported sort type at this time.

Resource URL parameters

You can add parameters to your resources requests to return more specific results or to page through large result sets.

Fields parameter

Every request URL supports the optional fields parameter. The value of the fields parameter is a comma-separated list of resource properties that should be returned in the response. The ‘’field’’ parameter tells the server to return a certain set of fields. (This may be more or less fields that what is returned by default)

Example: To return the titles and creation dates of the most recent blog posts, the request URL would be:

http://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost/recent?fields=title,createdDate

Most requests have the option to request additional information about the resources returned. For example, when you request a Blog Post, it returns the screen name of the member who created it. Normally you would need to perform a second request to retrieve the name and profile photo of the author. With sub-resources you specify that you want fields from related content like the author’s name and profile photo returned as well.

Example: Request for the all recent blog posts with the author’s full name and icon for each item:

GET http://external.ningapis.com/xn/rest/1.0/BlogPost/recent?fields=title,descirption,author.fullName,author.iconUrl

There are two main advantages to using sub-resources:

  1. If multiple resources share the same sub-resources (e.g., several Photos with the same author), sending the sub-resource once reduces the size of the response.
  2. Parsing of responses by client libraries is simpler since a parser can be written to handle each sub-resource type and re-used with multiple resources.

Pagination parameters

All requests that specify a sort order support 2 parameters used for paging:

anchor
Unique identifier for the last-returned page of results
count
The number of results to return, with a maximum of 100. This parameter also supports negative values down to -100. Negative count parameters returns results before the anchor parameter.

Example: Request that retrieves the twenty most recent blog posts would be:

http://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost/recent?count=20

Example: Request that retrieves the next twenty blog posts would be:

http://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost/recent?anchor=UxbFfoc1dq0wX1t,count=20

Filter parameters

To retrieve more specific results, there are several parameters that can be used to filter the kind of data you’re returning.

Note

Some resources don’t support every filter parameter. Additionally, some filters can be used more than once. Check the resource reference section for a full list of filter parameters that a particular resource supports.

approved
Only include posts that have been approved by the Network Creator, Administrators, or content moderators
author
Only include content from a specific member of the site
id
Retrieve only a specific content item
private
If true the request will only include content that has it’s visibility marked as me or friends. If request is not made by the Network Creator, the server will return 403 Forbidden.

Other parameters

There are a handful of query parameters that tweak behavior to work around special edge cases.

xn_pretty
If set to true, then JSON is pretty printed, making it much easier to read. This is useful when debugging.
xn_always200
XMLHttpRequests have a tendency to not provide a body for non-200 responses. Setting this parameter to true causes all responses to be 200. The caller should use the status field of the response to get the real status code.
xn_method
IE 8’s support of cross-origin resource sharing doesn’t preflight requests to allow non-GET or POST methods. Setting this parameter overrides the actual method of the request.
xn_authInBody
IE 8’s support of cross-origin resource sharing doesn’t preflight requests to allow custom headers. If this parameter is set to true, then the first line (i.e., everything up to ASCII 10, aka, “n”) of the body is treated as the value of the Authorization header.

Warning

Unknown parameters, duplicate parameters, or invalid parameter values will result in 400 error responses

Request Types

Reading Content

The GET command is used to retrieve specific content or sets of content.

Example: Retrieve the 2 most recent photos on a site:

GET /xn/rest/apiexample/1.0/Photo/recent?fields=image.url,title&count=2 HTTP/1.1
Host: external.ningapis.com
Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"

Example: Retrieve the 2 most recent photos from a site

curl -H 'Authorization: OAuth oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"' \
    'https://external.ningapis.com/xn/rest/apiexample/1.0/Photo/recent?xn_pretty=true&fields=image.url,title&count=2'

Creating Content

The POST command is used for creating new content. The fields are specified as form-encoded parameters using either application/x-www-form-urlencoded or multipart/form-data. When uploading a file, the parameter should be named file.

Example: Create a blog post:

POST /xn/rest/apiexample/1.0/BlogPost?fields=title HTTP/1.1
Host: external.ningapis.com
Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"
Content-Length: 47
Content-Type: application/x-www-form-urlencoded
title=BlogPost&description=BlogPost description

Example: Create a blog post using cURL

curl -H 'Authorization: OAuth oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"' \
    -d 'title=BlogPost' \
    -d 'description=BlogPost description'
    'https://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost?fields=title'

Note

Content creation respects the approval settings of the Ning Network. If the moderation is on then posts by members must be approved first.

Updating Content

The PUT command is used to update existing content on a Ning Network. The fields are specified as form-encoded parameters using application/x-www-form-urlencoded. Unknown or read-only fields will be ignored.

Example: Update a photo:

PUT /xn/rest/apiexample/1.0/Photo?id=3011345:Photo:1077 HTTP/1.1
Host: external.ningapis.com
Authorization: oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"
Content-Length: 85
Content-Type: application/x-www-form-urlencoded

title=Updated Photo Title&description=Updated Photo Description&id=3011345:Photo:1099
curl -X PUT \
    -H 'Authorization: OAuth oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"' \
    -d 'id=3011345:Photo:1099' \
    -d 'title=Updated Photo Title' \
    -d 'description=Updated Photo Description' \
    'https://external.ningapis.com/xn/rest/apiexample/1.0/Photo?xn_pretty=true'

Deleting Content

The DELETE command is used to delete content on a Ning Network. The ID is specified as a parameter and you can only delete one content item at a time.

Example: Delete a photo:

DELETE http://external.ningapis.com/xn/rest/examplenetwork/1.0/Photo?id=1220998:Photo:5581

Example: Delete a photo using cURL

curl -X DELETE \
    -H 'Authorization: OAuth oauth_signature_method="PLAINTEXT",oauth_consumer_key="0d716e57-5ada-4b29-a33c-2f4af1b26837",oauth_token="a2f85402-f16c-4677-91e2-a334d362ad47",oauth_signature="f0963fa5-1259-434f-86fc-8a17d14b16ca%26b42a0833-e1e2-4b02-a906-258a157bc702"' \
    'https://external.ningapis.com/xn/rest/apiexample/1.0/Photo?xn_pretty=true&id=3011345:Photo:1099'