Response Overview

Response Structure

Responses from resources are formatted as JSON objects. The exact structure of the response object will vary depending on the resource, parameters, and request type. Additional details on the exact structure of a response can be found in the sections below and on the Request Types page.

Caching

The data returned by queries is not cached, metadata used for determining access rights and site properties is cached for less than ten seconds.

This means that if a photo has it’s visibility changed from me to all, it is possible that a request made by another member within ten seconds of the change will not include the photo in the response.

On the other hand, an update to a blog post’s title will be see immediately by the next request.

Successful Response

Read responses

There are 3 types of responses you can get from a successful READ request: single item, multi-item, and list

Single Item Response

Single item requests are requests for a specific content item by it’s ID. The response contains two properties: success and entry. Success will be true and entry will contain a JSON representation of the requested item. If the requested item cannot be found the server will respond with a 404 error.

Example: If you made a request for a blog post on a site:

GET http://external.ningapis.com/xn/rest/apiexample/1.0/BlogPost?id=2570916:BlogPost:322

Your response would be structured like the following:

{
    "success": true,
    "entry": [{
        "id": "2570916:BlogPost:322",
        "author": "3ixs6bzjxfkv6",
        "title": "Cycling Las Vegas",
        "description": "Cycling is Las Vegas is better than you would think"
    }],
}

Multi-Item Response

The request is made for multiple content items using multiple id parameters. The resulting entry resource will be an array of JSON representations or an empty array of if none of the items could be found.

Example: If you made a request for 2 photos on a site:

GET http://external.ningapis.com/xn/rest/examplenetwork/1.0/Photo?&id=1220999:Photo:5605&id=1220999:Photo:5591

Your response would be structured like the following:

{
  "success" : true,
  "entry" : [ {
    "id" : "1220999:Photo:5591",
    "author" : "exampleuser",
    "createdDate" : "2010-01-26T23:20:13.591Z"
  }, {
    "id" : "1220999:Photo:5605",
    "author" : "qrwc2g2iqjhi",
    "createdDate" : "2010-02-26T20:49:06.605Z"
  } ],
  "resources" : {
  }
}

List Response

Requests for lists of items (such as /BlogPost/recent) will return an array of JSON representations or an empty array. It will also contain information for paginating through the result set.

anchor

A token used to identify the current page of results relative to the entire set

firstPage

If true, this is the first page of the result set

lastPage

If true, this is the last page of the result set

Example: If you made a request for the 5 most recent photos on a site:

GET http://external.ningapis.com/xn/rest/examplenetwork/1.0/Photo/recent?count=5

Your response would be structured like the following:

{
  "success" : true,
  "anchor" : "sBLHSuPH8xNPdBxyRHy3pw",
  "firstPage" : true,
  "lastPage" : false,
  "entry" : [ {
    "id" : "1220999:Photo:5868",
    "author" : "exampleuser",
    "createdDate" : "2010-06-02T10:54:41.868Z"
  }, {
    "id" : "1220999:Photo:5605",
    "author" : "qrwc2g2iqjhi",
    "createdDate" : "2010-02-26T20:49:06.605Z"
  }, {
    "id" : "1220999:Photo:5591",
    "author" : "exampleuser",
    "createdDate" : "2010-01-26T23:20:13.591Z"
  }, {
    "id" : "1220999:Photo:5590",
    "author" : "exampleuser",
    "createdDate" : "2010-01-26T23:09:02.590Z"
  }, {
    "id" : "1220999:Photo:5589",
    "author" : "exampleuser",
    "createdDate" : "2010-01-26T21:32:44.589Z"
  } ],
  "resources" : {
  }
}

Count Response

Count requests return the number of items created after a user specified date. For a successful count request, your response will contain two properties: success and count. success will be true and count will be the number of items in the result set.

{
    "success": true,
    "count": 23
}

Create responses

For a successful CREATE request, your response will contain two properties: success and id. success will be true and id will be the ID of the item you just created.

Example: If you made a request to 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

The response would look like:

{
    "success": true,
    "id": "123:Photo:456"
}

Update responses

For a successful UPDATE request, your response will contain 1 property: success and it’s value will be true

Example: if you made a request to 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

The response would look like:

{
    "success": true
}

Delete responses

For a successful DELETE request, your response will contain 1 property: success and it’s value will be true

Example: if you made a request to delete a photo:

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

The response would look like:

{
    "success": true
}

Failed Response

If a request fails, there are several pieces of info that will help clue you into what’s going on:

success

For failed requests, this will always be false

reason

A human readable reason for the failure

status

The HTTP status code for the request

code

A numeric value indicating the category this error belongs to. This is meant to be consumed programmatically.

subcode

A numeric value that indicates the specific error that was triggered. This is meant to be consumed programmatically.

trace

An identifier that is used by Ning to debug issues. Include this number in any bug reports.

Here is an example of a failed response:

{
    "success": false,
    "reason": "Count must be less than 100, but got: 500",
    "status": 400,
    "code": 1,
    "subcode": 7,
    "trace": "4a076440-f132-4fbf-81bf-8f4d2eefa4c7"
}