Response format v1.2

This page describes the response formats defined by the Permission Marketing API. All endpoints will return data conforming to this specification.

Each example assumes an HTTP status in the range 200-299, please see error handling for more information on error states and codes.

Handling a response

A successful response format will always contain the following attributes:

Attribute Type Description Methods 
status
 string Always "OK" for a successful request. GET POST PUT DELETE 
response
 object Object describing the response. GET POST PUT DELETE 
data
 array/object The response data. If the response consists of a single resource, this element will be an object; otherwise it will be an indexed array. The contents of this array/object varies by endpoint. GET POST PUT DELETE 
next
 int/string/null Value representing the resource following the last returned resource. This can be used in a subsequent request as a value for the "start" argument in order to obtain the next "page" of results. A value of null indicates no more resources are available. GET 
count
 int The number of resources returned in this response. GET POST PUT DELETE

GET response

{
    "status":     "OK",
    "response":   {
        "count":       10,
        "next":        123456,
        "data":        [ /* collection */ ] or { /* single resource */ }
    }
}

A collection will always be returned unless the request is filtered by id.

HEAD response

HTTP/1.1 200 OK
Date: Thu, 25 Apr 2013 08:22:28 GMT
Server: Apache
Cache-Control: no-cache
Expires: Sat,  9 Sep 1989 11:00:00 GMT
X-SuT-Server: SUTAPI v0.0.1
Connection: close
Content-Type: application/json; charset=UTF-8

HTTP 404 (resource not found) is returned if no resources matched the filter criteria.

POST/PUT response

{
    "status":     "OK",
    "response":   {
        "count":       1,
        "next":        null,
        "data":        [ /* collection */ ] or { /* single resource */ }
    }
}

The whole resource will be returned as if a GET request had been issued.

DELETE Response

{
    "status":     "OK",
    "response":   {
        "count":       1,
        "next":        null,
        "data":        [ /* collection */ ] or { /* single resource */ }
    }
}

Only the id of the affected resource(s) will be returned.

HTTP status

A successful response assumes an HTTP status in the range 200-299:

Method Status Description 
GET
 200 OK 
HEAD
 200 OK 
POST
 202 Accepted 
PUT
 200 OK 
DELETE
 200 OK