An Introduction to GAP and the API
The Global Alerting Platform (GAP) is a device independent hub for messaging devices providing location tracking, emergency alerting, message routing and storage.
GAP also acts as a gateway to terrestrial messaging systems including, but not limited to, GSM, SMS and email.
Whether your message is a position report, an emergency alert or a simple text message, our hub can transform and route the message to any destination. For example, if you are a single handed fisherman you can route a man-overboard alert directly to the search and rescue services or if you are hiking in the mountains, you can configure your account to automatically send your location to all your friends. In a lone worker scenario, you could send a message from your Iridium SBD based device to another user with a totally different device on another terrestrial or satellite network.
Emergency messages can be relayed to first responder centres or directly to SAR authorities, based on location and nationality. GAP is fully integrated with the GEOS International Emergency Response Coordination Centre (IERCC). Please note that extra charges may apply.
In a world of rapid technological innovation and ever changing standards, the ability to interoperate between messaging systems is an increasing problem. Being able to automatically translate from one message format to another without user intervention is a unique service provided by GAP. For example, it is possible to send a text message from your handheld device and have it delivered as an email and vice versa. Similarly, you can send an SMS message from a terrestrial phone and have that delivered as an Iridium SBD message.
Powered by Microsoft Azure®, Microsoft’s cloud computing technology, GAP has been designed from scratch to provide near limitless scalability, high availability and integrity. Distributed across a network of globally inter-connected datacentres, GAP provides a secure way to globally route messages between devices, corporate systems, search and rescue authorities and personal end points.
Access to the platform can be achieved through a number of mechanisms depending on the requirements. GAP provides a customisable web portal that allows consumers and business users to configure devices, route messages and plot locations and tracks. This documentation describes the REST API. This mechanism allows developers to integrate devices of their own or build their own applications for consuming device data.
Using the ‘compute on demand’ features of Windows Azure, GAP allows for dynamic changes in traffic load ensuring there is always sufficient compute power to cope with growth. Additional compute power can be provisioned at the 'press of a button'. The underlying software has been architected to be horizontally scalable, meaning it scales linearly with increased compute power.
One of the main advantages provided by the platform is robust availability based on extensive redundancy achieved with virtualization technology. GAP provides numerous levels of redundancy to provide maximum availability of customers data. Data is replicated to three separate nodes within the platform to minimize the impact of hardware failures. Customers can leverage the geographically distributed nature of the platform infrastructure by creating a multiple accounts to provide hot-failover capability. In such a scenario, customers may create custom roles to replicate and synchronize data between datacentres.
Confidentiality ensures that a customer's data is only accessible by authorized entities. GAP provides confidentiality via the following mechanisms:
- Identity and Access Management - Ensures that only properly authenticated entities are allowed access.
- Isolation – Beyond authenticating access to data, compute and storage elements are logically or physically separate.
- Encryption - Used internally within the platform for protecting control channels and is provided optionally for customers who need rigorous data protection capabilities.
The platform has multiple levels of monitoring and integrity checking. Each compute node has a monitoring agent that monitors the health of the virtual machine (VM) node on which it runs. If the agent fails to respond, the platform reboots the VM. In case of hardware failure, the platform automatically creates a new hardware node and reprograms the network configuration to restore the service to full availability.
API V2
Device Patch
Devices now support the Patch option. That means you do can send back just those properties you wish to update. Please contact support if there are other objects you wish to Patch.
eTags
Some objects such as Devices and Users now support eTags. An object's eTag can be retrieved via a GET request. When performing a PUT request the eTag can be optionally included. When the eTag is included, the underlying object will only be updated if the eTag matches. The object will always be updated if the eTag is not included.
Continuation Tokens
Some endpoints implement pagination for record retrieval. When additional records are available, a continuation token (
The following endpoints are paged by 1,000 records per request:
- Alerts
- Device Log
- MO Messages
- MT Messages
The following endpoints are paged by 10,000 records per request:
- Devices
- Users
Things to know about the REST API
The API is entirely HTTP-based. Methods to retrieve data from the API require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct verb. HTTP Response Codes are meaningful.
The API is a RESTful resource. The API attempts to conform to the design principles of Representational State Transfer (REST). Simply change the Accept header of a request to get results in the format of your choice e.g. Accept: application/json. The API presently supports the XML, JSON and JSONP data formats, with some methods only accepting a subset of these formats.
Rest API Limits
- Clients may access a maximum of 1000 results from a single request
- Requests for more than the limit will result in a reply with a status code of 200 and an result containing 1000 records in the format requested.
- There are limits to how many calls and changes you can make in a day.
- API usage is rate limited with additional fair use limits to protect GAP from abuse.
- V2 of the API uses a continuation token to allow the user to request the next page of results.
The GAP API provides built-in support for a subset of the Open Data Protocol (OData) query string parameters that a client can use to sort or filter the results.
| Parameter | Description | Example |
|---|---|---|
| $filter | Selects entries that match a Boolean expression. | https://api.globalalerting.com/V2/1234/devices?$filter=contains(FriendlyName, 'MyDevice') https://api.globalalerting.com/V2/1234/devices?$filter=EmergencyState eq 'Emergency' |
| $orderby | Orders the results by the specified property. | https://api.globalalerting.com/V2/1234/devices?$orderby=Name |
| $skip | Skips the first n elements. | https://api.globalalerting.com/V2/1234/devices?$skip=2 |
| $top | Returns the first n elements in the list. If combined with $orderby, the list is sorted first, and the first n elements of the sorted list are returned (max 1000). | https://api.globalalerting.com/V2/1234/devices?$top=10 |
Some Further Examples:
1. Return MO messages filtering on sequence number and return json
- https://api.globalalerting.com/V2/tenantCode/devices/deviceId/momessages?$filter=SequenceNumber eq 1
2. Return MO messages filtering on start dates/end dates
- https://api.globalalerting.com/V2/tenantDode/devices/deviceId/momessages?$filter=SentFromDevice ge 2014-05-16T01:05:00Z and SentFromDevice le 2014-05-30T10:04:00Z
2. Return last 10 MO messages
- https://api.globalalerting.com/V2/tenantCode/devices/deviceId/momessages?$top=10
Authentication
There are two ways to authenticate to the API, Basic Authentication or using your API Key.
Basic Authentication
Using basic authentication is as simple as adding the basic authorization header in each API request. Basic Authentication overview from wikipedia
API Key
The GAP API also supports the use of an key. To use your API key with the API, the key should be added to the request header. The Key name is "X-GAPAPIKEY". Whenever a header with this key is present, API Key Authentication is used and takes precedence.
Web Hooks
The Web Hooks Service allows your system to be notified every time a specified action occurs on GAP. We currently support web hooks for Devices, Users, Tenants, MO Messages, and Event Notifications.
To use this service, you need to provide us with the URL of your HTTP endpoint that we will use to POST data. Each item is sent individually soon after the action happens on GAP. The item is serialized using JSON and includes an indicatior of the item type, the action taken, and the item itself. You can choose either basic or no authentication. We have a retry mechanism in place that will repeat the call several times until success HTTP status code is received.