{"id":3112,"date":"2014-01-23T14:28:38","date_gmt":"2014-01-23T22:28:38","guid":{"rendered":"http:\/\/107.21.221.225\/ning3help\/?page_id=3112"},"modified":"2019-10-21T08:11:57","modified_gmt":"2019-10-21T15:11:57","slug":"ning-3-0-api-requests","status":"publish","type":"page","link":"https:\/\/www.ning.com\/ning3help\/ning-3-0-api-requests\/","title":{"rendered":"Ning 3.0 API Requests"},"content":{"rendered":"
\n

Request Overview<\/h1>\n
\n

Rate Limits<\/h2>\n

The Ning API has a throttle rate of 20 requests per second, per Ning Network.
\nWhen requests go over this limit, the API will return a 503 HTTP response.<\/p>\n<\/div>\n

\n

Resource URL structure<\/h2>\n

A typical resource URL looks like:<\/p>\n

\n
https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/BlogPost\/recent<\/pre>\n<\/div>\n
A resource URL consists of several parts:<\/p>\n
\n
Ning API Domain<\/strong> https:\/\/external.ningapis.com<\/span><\/tt><\/dt>\n
The base URL for the Ning API<\/dd>\n
Namespace Prefix<\/strong> \/xn\/rest<\/span><\/tt><\/dt>\n
This defines that we are using the Ning API.<\/dd>\n
Ning Subdomain<\/strong> \/apiexample<\/span><\/tt><\/dt>\n
Specifies the Ning Ning Network that we are making requests to. You must use the Ning subdomain, you cannot use a custom domain.<\/dd>\n
API Version<\/strong> \/2.0<\/span><\/tt><\/dt>\n
Currently Ning is on version 2.0 of it\u2019s 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<\/a><\/dd>\n
Resource Type<\/strong> \/BlogPost<\/span><\/tt><\/dt>\n
The data we are working with.<\/dd>\n
Sort Ordering<\/strong> \/recent<\/span><\/tt><\/dt>\n
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.<\/dd>\n<\/dl>\n<\/div>\n
\n
Resource URL parameters<\/h2>\n
You can add parameters to your resources requests to return more specific results or to page through large result sets.<\/p>\n
\n
Fields parameter<\/h3>\n
Every request URL supports the optional fields<\/span><\/tt> parameter. The value of the fields<\/span><\/tt> parameter is a comma-separated list of resource properties that should be returned in the response. The \u2018\u2019fields\u2019\u2019 parameter tells the server to return a certain set of fields. (This may be more or fewer fields than are returned by default)<\/p>\n
Example: To return the titles and creation dates of the most recent blog posts, the request URL would be:<\/p>\n
\n
https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/BlogPost\/recent?fields=title,createdDate<\/pre>\n<\/div>\n
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\u2019s name and profile photo returned as well.<\/p>\n
Example: Request for the all recent blog posts with the author\u2019s full name and icon for each item:<\/p>\n
\n
GET https:\/\/external.ningapis.com\/xn\/rest\/2.0\/BlogPost\/recent?fields=title,descirption,author.fullName,author.iconUrl<\/pre>\n<\/div>\n
There are two main advantages to using sub-resources:<\/p>\n
    \n
  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.<\/li>\n
  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.<\/li>\n<\/ol>\n<\/div>\n
    \n
    Pagination parameters<\/h3>\n
    All requests that specify a sort order support 2 parameters used for paging:<\/p>\n
    \n
    anchor<\/strong><\/dt>\n
    Unique identifier for the last-returned page of results<\/dd>\n
    count<\/strong><\/dt>\n
    The number of results to return, with a maximum of 100. This parameter also supports negative values down to -100. Negative count<\/span><\/tt> parameters returns results before the anchor<\/span><\/tt> parameter.<\/dd>\n<\/dl>\n
    Example: Request that retrieves the twenty most recent blog posts would be:<\/p>\n
    \n
    https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/BlogPost\/recent?count=20<\/pre>\n<\/div>\n
    Example: Request that retrieves the next twenty blog posts would be:<\/p>\n
    \n
    https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/BlogPost\/recent?anchor=UxbFfoc1dq0wX1t,count=20<\/pre>\n<\/div>\n<\/div>\n
    \n
    Filter parameters<\/h3>\n
    To retrieve more specific results, there are several parameters that can be used to filter the kind of data you\u2019re returning.<\/p>\n
    \n
    Note<\/p>\n
    Some resources don\u2019t support every filter parameter. Additionally, some
    \nfilters can be used more than once. Check the resource reference section
    \nfor a full list of filter parameters that a particular resource supports.<\/p>\n<\/div>\n
    \n
    approved<\/strong><\/dt>\n
    Only include posts that have been approved by the Network Creator, Administrators, or content moderators<\/dd>\n
    author<\/strong><\/dt>\n
    Only include content from a specific member of the site<\/dd>\n
    id<\/strong><\/dt>\n
    Retrieve only a specific content item<\/dd>\n
    private<\/strong><\/dt>\n
    If true the request will only include content that has it\u2019s visibility marked as me<\/span><\/tt> or friends<\/span><\/tt>. If request is not made by the Network Creator, the server will return 403 Forbidden.<\/dd>\n<\/dl>\n<\/div>\n
    \n
    Other parameters<\/h3>\n
    There are a handful of query parameters that tweak behavior to work around special edge cases.<\/p>\n
    \n
    xn_pretty<\/strong><\/dt>\n
    If set to true, then JSON is pretty printed, making it much easier to read. This is useful when debugging.<\/dd>\n
    xn_always200<\/strong><\/dt>\n
    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.<\/dd>\n
    xn_method<\/strong><\/dt>\n
    IE 8\u2019s support of cross-origin resource sharing doesn\u2019t preflight requests to allow non-GET or POST methods. Setting this parameter overrides the actual method of the request.<\/dd>\n
    xn_authInBody<\/strong><\/dt>\n
    IE 8\u2019s support of cross-origin resource sharing doesn\u2019t 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, \u201cn\u201d) of the body is treated as the value of the Authorization header.<\/dd>\n<\/dl>\n
    \n
    Warning<\/p>\n
    Unknown parameters, duplicate parameters, or invalid parameter values will result in 400 error responses<\/p>\n<\/div>\n<\/div>\n<\/div>\n
    \n
    Request Types<\/h2>\n
    \n
    Reading Content<\/h3>\n
    The GET<\/strong> command is used to retrieve specific content or sets of content.<\/p>\n
    Example: Retrieve the 2 most recent photos on a site:<\/p>\n
    \n
    GET \/xn\/rest\/apiexample\/2.0\/Photo\/recent?fields=image.url,title&count=2 HTTP\/1.1\nHost: external.ningapis.com\nAuthorization: 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\"<\/pre>\n<\/div>\n
    Example: Retrieve the 2 most recent photos from a site<\/p>\n
    \n
    \n
    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\"'<\/span> \\<\/span>\n    'https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/Photo\/recent?xn_pretty=true&fields=image.url,title&count=2'<\/span>\n<\/pre>\n<\/div>\n<\/div>\n<\/div>\n
    \n
    Creating Content<\/h3>\n
    The POST<\/strong> command is used for creating new content. The fields are specified as form-encoded parameters using either application\/x-www-form-urlencoded<\/span><\/tt> or multipart\/form-data<\/span><\/tt>. When uploading a file, the parameter should be named file<\/span><\/tt>.<\/p>\n
    Example: Create a blog post:<\/p>\n
    \n
    POST \/xn\/rest\/apiexample\/2.0\/BlogPost?fields=title HTTP\/1.1\nHost: external.ningapis.com\nAuthorization: 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\"\nContent-Length: 47\nContent-Type: application\/x-www-form-urlencoded\ntitle=BlogPost&description=BlogPost description<\/pre>\n<\/div>\n
    Example: Create a blog post using cURL<\/p>\n
    \n
    \n
    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\"'<\/span> \\<\/span>\n    -d 'title=BlogPost'<\/span> \\<\/span>\n    -d 'description=BlogPost description'<\/span>\n    'https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/12.0\/BlogPost?fields=title'<\/span>\n<\/pre>\n<\/div>\n<\/div>\n
    \n
    Note<\/p>\n
    Content creation respects the approval settings of the Ning Network. If the moderation is on then posts by members must be approved first.<\/p>\n<\/div>\n<\/div>\n
    \n
    Updating Content<\/h3>\n
    The PUT<\/strong> 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<\/span><\/tt>. Unknown or read-only fields will be ignored.<\/p>\n
    Example: Update a photo:<\/p>\n
    \n
    PUT \/xn\/rest\/apiexample\/2.0\/Photo?id=3011345:Photo:1077 HTTP\/1.1\nHost: external.ningapis.com\nAuthorization: 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\"\nContent-Length: 85\nContent-Type: application\/x-www-form-urlencoded\n\ntitle=Updated Photo Title&description=Updated Photo Description&id=3011345:Photo:1099<\/pre>\n<\/div>\n
    \n
    \n
    curl -X PUT \\<\/span>\n    -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\"'<\/span> \\<\/span>\n    -d 'id=3011345:Photo:1099'<\/span> \\<\/span>\n    -d 'title=Updated Photo Title'<\/span> \\<\/span>\n    -d 'description=Updated Photo Description'<\/span> \\<\/span>\n    'https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/1.0\/Photo?xn_pretty=true'<\/span>\n<\/pre>\n<\/div>\n<\/div>\n<\/div>\n
    \n
    Deleting Content<\/h3>\n
    The DELETE<\/strong> 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.<\/p>\n
    Example: Delete a photo:<\/p>\n
    \n
    DELETE https:\/\/external.ningapis.com\/xn\/rest\/examplenetwork\/1.0\/Photo?id=1220998:Photo:5581<\/pre>\n<\/div>\n
    Example: Delete a photo using cURL<\/p>\n
    \n
    \n
    curl -X DELETE \\<\/span>\n    -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\"'<\/span> \\<\/span>\n    'https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/Photo?xn_pretty=true&id=3011345:Photo:1099'<\/span>\n<\/pre>\n<\/div>\n<\/div>\n<\/div>\n
    <\/p>\n<\/div>\n
    <\/p>\n<\/div>\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    Request Overview<\/p>\n
    Rate Limits
    \nThe Ning API has a throttle rate of 20 requests per second, per Ning Network.
    \nWhen requests go over this limit, the API will return a 503 HTTP response.<\/p>\n
    Resource URL structure
    \nA typical resource URL looks like:<\/p>\n
    https:\/\/external.ningapis.com\/xn\/rest\/apiexample\/2.0\/BlogPost\/recent<\/p>\n
    A resource URL consists of several parts:<\/p>\n
    Ning API Domain https:\/\/external.ningapis.com
    \nThe base URL for the Ning API
    \nNamespace Prefix \/xn\/rest
    \nThis defines that we are using the Ning API.
    \nNing Subdomain \/apiexample
    \nSpecifies the Ning Ning Network that we are making requests to. You must use the Ning subdomain, you cannot use a custom domain.
    \nAPI Version \/2.0
    \nCurrently Ning is on version 2.0 of it\u2019s 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<\/a>
    \nResource Type \/BlogPost
    \nThe data we are working with.
    \nSort Ordering \/recent
    \nThe 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.<\/p>\n
    Resource URL parameters
    \nYou can add parameters to your resources requests to return more specific results or to page through large result sets.<\/p>\n
    Fields parameter
    \nEvery request URL supports the optional fields parameter. The value …<\/p>\n","protected":false},"author":20,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":[],"yoast_head":"\n\n\n\n\n\n\n\n\n\n\n\n\t\n