Ning Developer Network

Ning Developer Admin

REST API Request URL Syntax

Creating Feed URLs for the Ning REST API

This page describes the URL syntax for version 1.0 of the Ning REST API. The available endpoints are detailed in the table below. To construct a URL corresponding to a particular endpoint, prefix the endpoint with http://app.ning.com/xn/atom/1.0. For example, to get a feed of content in the restaurants app, visit http://restaurants.ning.com/xn/atom/1.0/content. You may find our ATOM REST API example page useful as well.

A Note about Browsers

As recommended by the Atom specification, Ning emits Atom feeds with the MIME type application/atom+xml. Unfortunately, most popular web browsers (including Microsoft Internet Explorer and Mozilla Firefox) will prompt the user to download the feed as a file rather than display in the browser window. In order to view emitted feeds easily when experimenting with the Ning Atom API, you may need to reconfigure your browser.

Endpoints

The table below describes the available endpoints for GET actions.

Endpoints
Resource Operation Method Endpoint Comments
Content Query GET /content(C) Returns a feed of content entries.
Content Rollup Query GET /content/rollup(R) Returns a feed of <xn:rollup /> elements describing content rolled-up as indicated by R.
Application Query GET /application Returns a feed containing an <entry /> describing the current application, if that application exists.
Application Query GET /application/parent Returns a feed containing an <entry /> describing the current application's parent, if any.
Application Query GET /application/children Returns a feed containing an <entry /> for each of the application's children, if any.
Profile Query GET /profile(P) Returns a feed of profiles matching selector P
Tag Query GET /content(C)/tag Returns a feed of tags for content matching selector C.
Tag Query GET /tag(T)/content Returns a feed of content tagged with tags matching selector T.
Tag Rollup Query GET /content/tag/rollup Returns a feed of <xn:rollup /> elements describing tags against all content in the app rolled up by frequency.
Role Query GET /role Returns a feed of <xn:role /> elements describing the roles in the application
Role Query GET /role(R)/profile Returns a feed of profile entries that have roles described by R in the application.
Role Query GET /profile(P)/role Returns a feed of <xn:role /> elements for all roles granted in the application to profiles described by P.

These endpoints use the current Ning authentication scheme, which causes some redirects to be issued and cookies to be set on the first visit to the site. To bypass those redirects and cookies, add xn_auth=no to the request query string.

Selectors and Operators

The parts of the endpoints in parentheses are selectors. Selectors are filters that control what information is returned from the endpoint. They consist of field operator value triplets. Multiple filters are joined by &. Different field, operators, and values are valid in different kinds of selectors.

The following table lists the available operators.

Selector Operators
Operator Meaning
= equal to
<> not equal to
eic equal to, ignoring case
neic not equal to, ignoring case
> greater than
< less than
>= greater than or equal to
<= less than or equal to
like full-text search
likeic full-text search, ignoring case
in in a list of values

Most of these operators are pretty straightforward. The in, like, and likeic operators deserve some explanation, though.

When using the in operator, the supplied value must be an array. The filter matches objects that have a value equal to any one of the values in the array.

The like and likeic operators do a full-text search against the specified field. The search engine looks for the individual words in the supplied value (separated by space or %) and tries to find the most relevant matches. If you don't supply an order for a query that uses the like or likeic operator, you'll get results back ordered by relevance from the search engine.

Not all fields can be used with all operators, and not all fields and operators can be used in all seletors. The following tables list which fields and operators are available in the different kinds of selectors.

Profile Selectors
Field Operator(s) Value(s)
id = screen name of profile to retrieve
Role Selectors
Field Operator(s) Value(s)
id = name of role to retrieve
Content Rollup Selectors
Field Operator(s) Value(s)
field = type to rollup by content type
field = author to rollup by content author
Content Selectors
Field Operator(s) Value(s)
id in, =, != Content object ID. The in operator expects a list of IDs.
published =, !=, <, >, <=, >= Appropriately-formatted time/date string.
updated =, !=, <, >, <=, >= Appropriately-formatted time/date string.
type =, !=, eic, neic String
title =, !=, like, likeic String. With = or != and a null value, it matches content with (or without) a null title.
summary Same as title Same as title
my.developerAttribute Same as title developerAttribute is the name of any developerAttribute, otherwise same as title
Tag Selectors
Field Operator(s) Value(s)
value = String: tag value
author = String: tag creator screen name
createdDate =, !=, <, >, <=, >= Appropriately-formatted time/date string.

Types

What a value in a filter looks like depends on its type. The short description of how to put values in filters is "numbers can be integers or decimal, put single quotes around strings and use ISO-8601 dates for date/time stamps". A more exhaustive definition is in the following table.

Selector Value Formatting
Type Value Format
NUMBER double-precision IEEE 754 floating point number, e.g. 42 or -137.14
STRING '-delimited string with internal ' and \ characters escaped with \
DATE A complete ISO-8601-encoded date, plus hours, minutes, seconds, and timezone specifier
BOOLEAN true or false
NULL null
LIST [, followed by one or more comma-delimited NUMBERs, STRINGs, DATEs, BOOLEANs, or NULLs, followed by ]

Ordering and Paging

By default, the order of entries in a returned feed is unspecified for non-rollup feeds. To ensure that entries are put in a particular order, add an order field to the query string. Feeds of content entries support the following orders:

  • published
  • updated
  • type
  • title
  • summary
  • author
  • my.developerAttribute (for any developer attribute)

Feeds of tags support the following orders:

  • value
  • createdDate

Rollup feeds are sorted by default with the highest-frequency elements first. To make a tag rollup feed be ordered by tag value instead, use the value order.

Orders specified as order=field or order=field@A are ascending. Orders specified as order=field@D are descending.

Feeds contain a maximum of 100 elements, independent of how many elements match the endpoint selector. The total number of elements that match is available in the feed's <xn:size/> element. Additionally, the section of the total result set that appears in the feed is controlled with the from and to query string parameters. from inclusively indicates the (zero-based) position, in the entire result set, of the first element in the feed. to exclusively indicates the (zero-based) position, in the entire result set, of the last element in the feed. For example from=0&to=100 retrieves the first 100 elements of the result set. from=5&to=10 retrieves elements 5, 6, 7, 8, and 9.

Entries and XML Representations

For the XML representation of content objects and other Ning entities, see the XML Representations page.

Last updated by Ernie H. Aug 15.

Quick Links

We're Hiring

We are looking for talented and passionate individuals to join our growing team.

Visit our engineering jobs and see if Ning is right for you.

© 2008   Created by Ning Developer Admin

Badges  |  Report an Issue  |  Privacy  |  Terms of Service