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