External API Overview

In this section we give a quick overview of what you need to start using the external API, how you create remote requests and process the responses.

1. Prerequisites

To use the XtremePush test app you must have the app token from an application that is live in a user account on external-api.xtremepush.com. This token can be found in your App Home in Settings > General Settings as shown below.

If you don't have an app integrated with the XtremePush platform then you should check out our integration documentation first.

2. Creating remote requests

The external api methods are used by sending HTTPS POST requests with JSON body to external-api.xtremepush.com.

A typical API url looks like: https://external-api.xtremepush.com/api/external/{method name}/{model name}

The url is constructed from a combination of: Protocol identifier, HTTP secure is used for secure communication: https:// The domain name: external-api.xtremepush.com The api constant request identifier: /api/external/ The method name, action you are applying to data, for example: create The model name, this identifies the class storing the current model data that you want to change or view for example: campaign.

Each method also has its required attributes. Every method requires that the app token attribute is filled with the app token from your app settings on external-api.xtremepush.com. The API methods are covered in detail, in the following sections of the API documentation:

Campaign and related methods

• Campaign Methods
• Template Campaigns triggered/executed via API
• Tag/Attribute syncing methods
• Location Methods
• Segmentation Methods

 

Extracting Data via API

• Push Notification Methods
• Device Methods
• Tagging Methods
• Analytics Methods

 The API can be quickly tested from a command line terminal using curl (curl is a command line tool for transferring data with URL syntax). For example here is how you create a test push with curl and the XtremePush API:

$ curl -X POST -d '{"apptoken":"YOUR_APP_TOKEN","title":"Test","text":"Hi there!"} https://external-api.xtremepush.com/api/external/create/campaign

The command has the format of: the curl command followed by the -d option followed by the json body, followed by the API url. This is useful for some quick initial testing before integrating with your application.

3. Processing server responses

After making a https POST request to external-api.xtremepush.com using an API method any response is returned as a JSON formatted object. These JSON objects take the following form.

{
    "code"      : integer http error/success code
    "success"   : boolean - whether client request is successful
    "message"   : string system error message if code is error (4xx-5xx).
    "errors"    : errors list if success is false (optional)
    "data"      : contains array of response data (optional)
    "model"     : contains created / updated object attributes (optional)
}

In the above example we was creating a campaign by External API. The response for this API call is:

{
    "code": 200,
    "success": true,
    "message": "Campaign successfully created",
    "model": {
        "id": CAMPAIGN_ID,
        "text": "Testing Campaign is sent to subscribers to 15_01_04",
        "title": "Flag Test Campaign",
        ....
    },
}

Here is an example of possible failed request:

{
    "code": 400,
    "success": false,
    "message": "Campaign is not created",
    "errors": {
        "text": ["Text cannot be blank."]
    }
}

 

More detail on server responses in the following article:

https://support.xtremepush.com/hc/en-us/articles/115001058185-External-API-Responses-Status-Error-Codes