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:
https://external.ningapis.com/xn/rest/apiexample/2.0/BlogPost/recent
A resource URL consists of several parts:
- Ning API Domain https://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 /2.0
- Currently Ning is on version 2.0 of it’s Ning API, which is used with Ning 3.0 netowrks. For Ning 2.0 networks, use version 1.0 of the API, and the 1.0 documentation
- 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 ‘’fields’’ parameter tells the server to return a certain set of fields. (This may be more or fewer fields than are returned by default)
Example: To return the titles and creation dates of the most recent blog posts, the request URL would be:
https://external.ningapis.com/xn/rest/apiexample/2.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 https://external.ningapis.com/xn/rest/2.0/BlogPost/recent?fields=title,descirption,author.fullName,author.iconUrl
There are two main advantages to using sub-resources:
- 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.
- 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:
https://external.ningapis.com/xn/rest/apiexample/2.0/BlogPost/recent?count=20
Example: Request that retrieves the next twenty blog posts would be:
https://external.ningapis.com/xn/rest/apiexample/2.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/2.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/2.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/2.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/12.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/2.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 https://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/2.0/Photo?xn_pretty=true&id=3011345:Photo:1099'
