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 seen 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/2.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 in 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 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/2.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" : "2014-01-26T23:20:13.591Z"
}, {
"id" : "1220999:Photo:5605",
"author" : "qrwc2g2iqjhi",
"createdDate" : "2014-01-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/2.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" : "2013-06-02T10:54:41.868Z"
}, {
"id" : "1220999:Photo:5605",
"author" : "qrwc2g2iqjhi",
"createdDate" : "2013-02-26T20:49:06.605Z"
}, {
"id" : "1220999:Photo:5591",
"author" : "exampleuser",
"createdDate" : "2013-01-26T23:20:13.591Z"
}, {
"id" : "1220999:Photo:5590",
"author" : "exampleuser",
"createdDate" : "2013-01-26T23:09:02.590Z"
}, {
"id" : "1220999:Photo:5589",
"author" : "exampleuser",
"createdDate" : "2013-01-26T21:32:44.589Z"
} ],
"resources" : {
}
}
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/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
The response would look like:
{
"success": true,
"id": "123:BlogPost: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/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
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/2.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"
}
