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 HTTP POST requests with JSON body to an API Endpoint.

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 endpoint: 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.

Xtremepush manages a number of different instances located in different world regions. Each project on the platform is located in a single region, which could be selected when creating a project. You should use the corresponding API endpoint for each project:

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:

Importing and Managing Data

• User Profile Methods
• PII Deletion Methods
• Push in Data - Tag/Attribute syncing methods
• Push in Event Data - Real-time event methods

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) for                   use in logging so can be reviewed in the event of errors 
    "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 were 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 a 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