Server Payloads

From KickApps Documentation

A request to the REST server will return a JSON (JavaScript Object Notation) string.

Contents 1 JSON Converters 2 JSON Payload Format 2.1 JSON Example 3 XML Payloads

JSON Converters

JSON uses a simple, readable format that is easy to parse. Links to JSON converters for a variety of languages are listed at http://www.json.org/ (bottom of page).

The KickApps sample applications use the following converters.

Sample Application	Product
Java	org.json http://www.json.org/java/index.html
C#	Newtonsoft http://www.newtonsoft.com/products/json/
PHP	For versions 5.2.0 and later, use the json_decode function http://us.php.net/json_decode For versions 1.2.0-1.2.1, use the PECL extensions http://us.php.net/manual/en/install.pecl.php

JSON Payload Format

For each API call, the payload is described in the JSON Payload section. Each begins with a status indicator, either:

• "status":"1","error":"" appears at the start of the payload.

{"status":"1","error":"","callback":[{ }]}

• "status":"-1","error":"{message_text}" appears at the start of a payload with an error.

{"status":"-1","error":"text of error message","callback":[{ }]}

Payload contents are described for each API call. Each object in the payload is comprised from information presented in a "name":"value" format. If you use JavaScript, use the optional callback post parameter to include your application's callback function.

{"status":"1","error":"" [{"instance1":[{"name_1":value1,"name_2":"value_2","name_3":"value_3"}, {"instance2":[{"name_1":value1,"name_2":"value_2","name_3":"value_3"}, {"instance3":[{"name_1":value1,"name_2":"value_2","name_3":"value_3"}] }

Payloads use the following format:

• The body of the return is enclosed by curly brackets { }.
• Each object is enclosed by square brackets [ ] and is separated by a comma.
• Each instance of an object (as when a search returns five results) is separated by curly brackets { }, with each instance separated by a comma.
• A nested object that appears within an instance of another object is also separated by curly brackets { }.

For example, a member comment would be returned as follows, along with the member’s profile photo, username, the date the comment was posted, the comment’s messageId, the fromUserId of the member who posted the comment, and the text for the comment.

JSON Example

{"comments":[{"pathToPhoto":"1/users/madhatter_1_portrait.jpg","username":"madhatter","createdAt":"Yesterday, 07:13 PM","messageId":19716,"fromUserId":1358,"body":"My name says it all!"}, …

XML Payloads

For all calls, you can optionally add this parameter to receive XML payloads instead of JSON: payload_type=xml

The parameter can be either GET or POST.