1. Airship Support
  2. Features & Guides
  3. API

What are the best practices for the use of the Airship Messaging API?

 

Summary

The aim of this guide is to provide some best practice recommendations for interacting with Airship’s Messaging API. Following the recommendations contained will help you to build a resilient and scalable integration with Airship’s services as well as collect the information needed to support any technical issues related to our APIs.

Please reach out to Airship Support at http://support.airship.com if you need additional assistance.

Index

Logging

Airship’s services work at a high scale and as such we can only log a limited amount of information at the initial request level (1% of total successful requests) and only retain it for a defined period of time which can vary from a few hours to 30 days, depending on service. 

As such it is important that you log information regarding your API requests with Airship in order to have the information necessary to investigate when problems arise.

Recommendations for Logging

We recommend that you log the following information:

  • For All Requests:
    • Push ID
    • Timestamp (including timezone if not UTC)
    • Response Code
    • Operation ID (for non-push endpoints)
  • For All Errors or Timeout Concerns:
    • Full Request Including Headers (Omit/Redact Authentication Header)
    • Full Response from Airship's Servers

If you have a concern regarding latency in API response time or delivery time of notification, we will also ask for a full example of your API requests. See our more in-depth discussion in this guide.

Example Log

Successful Push:

202 Accepted
{
"ok": true,
"operation_id": "fb8ca0e2-a125-4369-9d89-43e9a0599d59",
"push_ids": [
"fedb72aa-5889-4ec0-a842-34c75134d160"
],
"message_ids": [],
"content_urls": [],
"localized_ids": []
}

Unsuccessful Push (missing "audience" field):

400 Bad Request
{
"ok": false,
"error": "Could not parse request body.",
"error_code": 40202,
"details": {
"error": "'audience' must be set"
},
"operation_id": "993a26af-c62e-49df-86f6-9e8fda5e9eaa"
}

Successful Add Tag:

200 OK
{
"ok": true
}

A Note on Proxy Servers

If your system uses a Proxy server to connect to Airship APIs you will need to plan to be able to provide logging showing direct interaction with Airship's APIs at https://go.urbanairship.com/api or https://go.airship.eu/api (EU Site) and not the proxy server’s address.

Things Airship Does Not Log

Airship does not have the ability to provide the following information:

  • Origin IP Address for requests to our servers
  • API Request in the original format sent to our API
  • Performance Metrics regarding individual accounts or applications

Timeout Settings

Airship’s servers have a 60-second timeout configured. API requests will generally return in under 1 second, however, this may increase during periods of high load.

We recommend that you set your server’s timeout in accordance with the 60 seconds in order to best tolerate any network and server load conditions. Setting a timeout below this threshold may result in client-side timeouts on your server which actually result in successful sends.

See the section below on Performance Concerns for more information regarding performance.

 

Retry Logic

Errors in HTTP requests can happen for a variety of reasons:

  • Problems with the request (Bad formatting, Incorrect Authentication, Missing information)
  • Network Issues
  • SSL Problems
  • Problems within Airship’s system (System Issues, High Traffic)

Our servers implement modern best practices such as auto-scaling, however, issues can occur both within and outside Airship’s system. You can sign up on our Status Page for notifications related to outages and maintenance events related to Airship.

Provided you have implemented a timeout as outlined above, errors should generally be infrequent. Airship guarantees 99.5% uptime service reliability. If your error rate is less than 0.5%, a retry may be your best path forward.

We recommend implementing an Exponential Backoff and Retry method on any 503 errors, as this indicates that the request was not accepted for processing. Our Java Server library implements this as default logic.

Other 5xx errors should be treated differently and may depend on the interaction. For Example GET requests can generally be retried, whereas retrying a POST request sending a push may result in sending multiple notifications.

Contact Airship support at https://support.airship.com if you are unsure if a notification was sent successfully.

Performance/Latency Concerns

Performance issues regarding the use of our API generally fall into 2 categories:

  • Response time of the API request
  • The time it takes for notification to be delivered

We will discuss strategies to improve performance in both these categories.

API Response Time

As mentioned in the Timeouts section of this guide, our average API response time is under 1 second, however, this can peak during times of high load. To make your systems more resilient to times when traffic peaks, we recommend the following:

  • Batch Individual requests when possible
    • Batching requests reduces the number of requests sent to the API, thus reducing the overall time in flight of the API requests
    • Unicast push requests (sent to individual Channel IDs or Named User IDs) can be sent in batches of up to 100
    • Tag updates can be sent in batches of up to 1000 users
    • Custom Events can be batched into groups of 100
  • Send in parallel 
    • Airship does not implement rate limiting on the number of requests 
    • Instead of using a single queue, use multiple queues to increase the rate at which you send requests

Delivery Speeds

Airship strives to send notifications as quickly as possible through our system. Network conditions, delays with Last Mile providers (FCM, APNS, SMS/Email Partners), and periods of high load can affect delivery speeds.

Depending on how complex your audience targeting and segmentation is in your request, there may be some improvements you can make that influence the speed of your notification sends:

  • Reduce the number of conditions (ie “tags”, "attributes") which are included
  • Do not use a “Not” condition 
    • In order to identify that a device does “not” have a tag, our system needs to check every tag set on the device which is more costly for performance
  • If Delivery speed is a concern, and you require complex segmentation for your use case, reach out to your Airship Account manager regarding our Boost Add-On

Max Response Size

When making certain “GET” requests, such as Channel or Named User Listings, you may encounter a 500 error due to exceeding the max size of the API response. 

If you are using non-mobile notification channels (ie Email, SMS, Open Channels) or set many tags, you are more likely to run into this issue.

You should generally be able to fix it by setting a “limit” on the API request which is less than the default of 1000 objects in the response.

Example:

curl -X GET \
'https://go.urbanairship.com/api/channels/?limit=500' \
-H 'Accept: application/vnd.urbanairship+json; version=3;' \
-H 'Authorization: Basic <BASIC_AUTH_STRING>' \
-H 'Content-Type: application/json'

Limitations of our APIs

There are no hard limits to the amount of data you can retrieve or request to Airship, however, there are recommended guidelines for each of our API endpoints that should be heeded in order to reduce the number of timeouts you may encounter when querying any of the below endpoints.

See this guide regarding our recommended guidelines for different endpoints

Throttling

Throttling is a service provided by Airship that is designed to alleviate any load issues that systems tied to your Airship project may incur from sending large amounts of notifications. By design, the throttling service will slow down notifications that are sent from Airship but it is not a guarantee of a rate of notifications being sent.

This service is an excellent temporary resource to leverage while building more resilient backend services to handle this traffic.

See this guide for a discussion of the considerations regarding how to determine if throttling would be a solution for your project and how to determine an appropriate rate.

TLS + Cipher Settings

As of October 26, 2020, Airship APIs will only support TLS 1.2 or higher. We have a list of our currently supported Cipher Suites available in our TLS FAQ.

Authentication

The Airship Messaging API supports both Basic Authentication and Bearer Token Authentication for most endpoints. Our Airship API Security document provides a map regarding which type of authentication is supported for the different endpoints.

Requests with incorrect authentication information will result in a 401 (Unauthorized) error.

IP Allowlist

Define one easy-to-maintain allowlist per company account. Each allowlist can contain an unlimited number of network ranges and/or IP addresses that can access your company’s project dashboards and API communication endpoints.

Only the listed account owner may define the allowlist. See our documentation on how to set up an allowlist.

Certificate Pinning

Airship’s public TLS certificate is subject to change without notice and we cannot provide a new certificate prior to being publicly available. As such we do not recommend pinning our certificate.

Airship IP Address

Airship does not have a static IP address that we can provide for our APIs. If your company requires this reach out to your Airship Account Manager or Airship Support to discuss options.

Expect 100-Continue

API POST requests sent using HTTP clients using an Expect: 100-Continue request header are significantly more likely to fail than those without the Expect: 100-Continue header.

See our more in-depth discussion in this guide.

Asynchronous nature of requests

It is important to note that most requests to Airship’s APIs are asynchronous in nature. Meaning that when you receive a 2xx response from our servers, we have acknowledged that we have successfully received the request for processing but our backend services may still be completing the transaction.

This has a few implications including:

  • A 202 response when sending a Push does not indicate that the request will result in a successful notification send. For example, we will validate that a Channel ID used in the request matches the correct format (UUID v4). However, we do not validate at the time of the initial request, that the Channel ID exists on the application or whether it is opted-in to receive notifications.
     
    202 Accepted
    {
    "ok": true,
    "operation_id": "fb8ca0e2-a125-4369-9d89-43e9a0599d59",
    "push_ids": [
    "fedb72aa-5889-4ec0-a842-34c75134d160"
    ],
    "message_ids": [],
    "content_urls": [],
    "localized_ids": []
    }

  • Registration API calls (SMS/Email/Open Channel, Named User Associations, Tag/Attribute Updates) may take time to fully process in our systems even though we return successful status with an identifier.

    As such, subsequent calls using the newly registered identifier may fail if that identifier is used immediately after registration. For example, registering a new SMS channel and then associating it to a Named User.

    You may receive a successful response on the initial request and get a Channel ID returned, however, the Channel ID is returned as “Not Found” when attempting to associate.

Depending on the reliability goals of your organization there can be a few options to address this concern:

  • Build an artificial delay into your requests between registration calls to increase the probability that the first call is successful
  • A more robust answer would be to make a GET request to the Channel ID or Named User ID Lookup API to ensure that the registration updates are correctly reflected and retry until it reflects correctly. This strategy is similar to what is implemented in our SDK-based registrations (ie iOS, Android, Web).

Use our Server Libraries

Airship provides Open Source server libraries for connecting to our APIs in Java, Python, Ruby, and PHP. 

You can access example requests in this guide using your preferred library.

We recommend using our Server libraries to make integrating with Airship’s APIs easier and because they implement many of our best practice recommendations, such as exponential backoff and retry. 

Airship Support can provide deeper support for issues and bugs that occur when implementing our Server libraries.

If one of our Server Libraries does not currently implement functionality that is available in our public API, reach out to Airship Support at http://support.airship.com.

Additional Usage Guides

Here are some further guides regarding the use of our Messaging APIs:

 

 

Was this article helpful?
2 out of 2 found this helpful
Submit a request