Request format v1.2
This page describes the request format defined by the Permission Marketing API. All endpoints will accept data conforming to this specification.
A request is returned in a success condition or an error condition.
This page describes the request format defined by the Permission Marketing API. All endpoints will accept data conforming to this specification.
A request is returned in a success condition or an error condition.
All requests to the Permission Marketing API:
GET /v1/exampleEndpoint
.All requests must be requested over SSL (HTTPS) and present valid authorisation credentials.
Filtering is optional, but may help you target specific resources quickly and efficiently. Not all attributes can be filtered, but a common attribute to sort by is id
:
id
being present or omitted.id
is present.id
is omitted.id
attribute. However, some endpoints allow a collection to be deleted if filtered by other attributes.The id
attribute can be provided in your URI or in the query string, for example GET /exampleEndpoint/123/
or GET /exampleEndpoint/?id=123
.
In addition to filtered attributes, the request format can contain the following arguments. All of these arguments are optional:
Attribute | Type | Description | Methods |
---|---|---|---|
count |
int | The number of resources to be returned which match the filter criteria. The response will return a count which is less than or equal to this value, depending on how many resources matched the filter criteria. The upper limit per request varies by endpoint, the default is "200". |
GET |
reverse |
bool | If "true", requests a descending sort; otherwise items will be sorted in ascending order. Defaults to "false". | GET |
sort |
string | Specifies an attribute on which to sort. If omitted, resources will be sorted by id . |
GET |
start |
int/string/null | The value of the first resource to fetch in a "page" - matched against the active sort attribute. This value doesn't have to specify an existing value; a partial value of "f" will return a page of results where the sort attribute is equal to or after "f". |
GET |
A "null" value in start
is treated as " " (empty string). All resources with a "null" value are omitted from the result set. Pagination is applied to the remaining resources (non-null) according to the supplied sort
and reverse
arguments.
A payload is a chunk of data contained within the request's body. Some methods require you to provide data in this format, others require a query string only. These two formats are explained below:
Format | Method | Description |
---|---|---|
Query string |
GET, HEAD, DELETE | Filters and sorting/pagination controls can be provided in a query string. The id attribute can also be provided in the URI. |
Request body |
POST, PUT | Resource attributes must be presented within the 'request body' and can be encoded in a variety of ways (see below). The id attribute can be provided in the URI or in a query string. |
In the PMAPI request payloads are decoded according to the specified Content-Type header. When issuing POST and PUT requests, please be sure to match your Content-Type header and the encoding of your payload. Please choose from the following supported types:
A query string is used for GET, HEAD and DELETE. For this reason, encoding on these methods is not available.
"GET /v1/exampleEndpoint/?foo=bar&sort=name&start=f&count=10" // Query string: { "foo" : "bar", "sort" : "name", "start" : "f", "count" : 10 } // Request body: { }
# Using Token authentication HEAD /v1/exampleEndpoint?id=123 HTTP/1.1 Host: api.sign-up.to Accept: application/json Authorization: SuTToken K/+zDxHsGi3H4xFxqIjtqo18ACW7bLnROKo9PJEv5YJEa7jou/J8qq0yY2Dg9/d/8aj7glze3yDqOeBynq3HI/ux/JU+shkK Date: Thu, 25 Apr 2013 08:25:54 GMT User-Agent: SUTAPI client v0.0.1 # Using CID/Hash authentication HEAD /v1/exampleEndpoint?id=123 HTTP/1.1 Host: api.sign-up.to Accept: application/json Authorization: SuTHash signature="4de3399fc4ce479838395eacccc6842461ef5059" Date: Thu, 25 Apr 2013 08:25:54 GMT User-Agent: SUTAPI client v0.0.1 X-SuT-CID: 12345 X-SuT-UID: 4567 X-SuT-Nonce: bbabf11dce3a7a8511a20d93af7f2b5a04edd43f
"POST /v1/exampleEndpoint" // Query string: { } // Request body: { "foo" : "bar", "firstname" : "John", "lastname" : "Smith" }
"PUT /v1/exampleEndpoint/123/" or "PUT /v1/exampleEndpoint/?id=123" // Query string: { "id" : 123 } // Request body: { "foo" : "bar", "firstname" : "John", "lastname" : "Smith" }
"DELETE /v1/exampleEndpoint/123/" or "DELETE /v1/exampleEndpoint/?id=123" // Query string: { "id" : 123 } // Request body: { }