The Appoxee API allows you to access major parts of Appoxee back-end functionality, both from the Server side and from the Device side.
The Service API is used mainly to send Push notifications to devices (see XXX). Other operations are performed through the SDK (see Android SDK API Usage and iOS SDK API Usage).
API Request
All data must be sent to the API in the JSON format, as an HTTP POST request. The data content type must be set to "applicaiton/json".
Each application has an 'AppSDKKey' and must provide a 'SECRET' key that needs to be requested individually by each Application that uses the API.
These parameters can be found via Appoxee back-end.
Additional security parameter added to ensure that no request is sent twice – the “random” parameter. This parameter added to JSON data, and the developer must ensure that it is random for every request. The Appoxee server checks each request's signature and random parameter, and rejects duplicated requrest.
The URL for the API is 'http://saas.appoxee.com/api/'
A request must provide the following constants (this example is given in the PHP format, for server-side usage):
- define('AppSDKKey', 'xxxx-xxxx-xxxx-xxxx');
- define('SECRET', 'mySecretCode'); // Application Secret
- define('URL', 'http://api.appoxee.com/api/');
Appoxee API variables and parameters consist of case-sensitive keys (alpha-numeric value, starting with a letter) and their length should be under 100 characters.
Authentication Signature
Appoxee's API security model ensures that every request has a unique secret signature.
This signature is passed as a parameter inside the “auth” JSON object (along with additional authentication-related information).
Signature parameters:
Parameter | Description | Example |
timestamp | the current time in a Unix timestamp in seconds | 1330607184 |
AppSDKKey | Appoxee secret code which is given per App. See it at Appoxee website (Settings->Apps & SDK Keys ->Your App ) | xxxxx-xxxxx-xxxxx-xxxxx |
SECRET | Appoxee secret code which is given per App to use specifically in API | sadfanbldkjfbslkdfnb |
signature | Created by using the MD5 hash function with the concatenation of the above parameters. The order is important | 65bd1d345fffc487ab1f15d837e94b38 |
random | Unique request parameter (can be used uniqid() or “random()”.) | 4f5cc37a93463 |
Signature PHP Example
$signature = md5($auth['timestamp'] . SECRET . AppSDKKey . random); |
API Response
The API response has the following format:
- If the call succeeded - HTTP 200 OK with no content
- If the call was invalid - HTTP 400 Bad Request
Response Body
The response body includes a description of the request result in JSON format. A call have one of the following results:
- If the call succeeded – a "Success" response” parameter
- If the requests was supposed to retrieve data - a “result” parameter, containing the result in the specified protocol.
- If the call failed - the error code and a message describing the error.
Example Success Response
{
"response": "Success"
}
Example Success Response whose Result is of Type Array
{
"response": "Success",
"result": [“tag1”, “tag2”]
}
Example Error Response for a Badly Formed Request
{
"response": "Error",
"code": 0,
"message": "Invalid request"
}
Action Definition Parameter
Each request must provide the “action” field, which defines the desired action. The Action field can be one of the following:
- “alias” – specify “Alias API” actions
- “tag” – specify the “Tag API” actions
- “key-value” – specify “Alias API” actions
- “attribute” – specify “Attribute API” actions
- “segment” – specify “Segmentation API” actions
- “push” – specify “Push API” actions