The AlphaTouch API is designed to allow developers to use their own back-end applications or processes to synchronize with to, or perform actions on a particular AlphaTouch Installation. The AlphaTouch API consists of two technological aspects that may need to be dealt with for a complete integration.
An API is an application programming interface - in short, it's a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format. REST stands for Representational State Transfer. This is an architectural pattern that describes how distributed systems can expose a consistent interface.
When people use the term 'REST API,' they are generally referring to an API accessed via HTTP protocol at a predefined set of URLs. These URLs represent various resources - any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE.
API Call requests must come from an IP address that is whitelisted in each of your Installations' management portal (in the API section). An API Call request will be declined if the installation in question does not have the request's originating IP address whitelisted. Please make sure you list all server IP addresses in the whitelist if the server will be making API requests.
The Whitelist for each installation can be located in the API Section of the installation's management portal.
Each AlphaTouch Installation has a unique API Key, which is accessible in the API Area of the Installation Management Portal (you must have API Permissions). You will need to store the API Key for each installation your are integrating with.
The API Key is to be included in the header of each of your API Calls so the AlphaTouch API knows which installation you are performing an API Call on.
/* Example API call To fetch a list of system administrators. Notice how the request is sent with the Unique API Key in the Header Parameters. */
curl --request GET
--url 'https://www.alphatouch.info/v1/administrator/list'
--header 'api-key: UNIQUE_API_KEY'
--header 'accept: application/json' The API Key will also be sent to your Webhook endpoint so you can determine which installation the incoming data is in reference to.
/* Example Data packet sent to your server's webhook endpoint by the AlphaTouch servers when a resident is deleted. Notice how the data contains the Unique API Key, as well as some other information about an event that took place on AlphaTouch. */
{
"api_key":"UNIQUE_API_KEY",
"action":"delete",
"entity":"resident",
"id":653
}
Important Notes Regarding API Keys
- It is essential that you keep your API Keys private. Having any one of them fall into the wrong hands would be considered a security breach. If an API Key should become compromised, the API Key can be reset in the API section of the Installation Management Portal.
- The AlphaTouch API is designed to be used by back-end server and processors. The integrator must create their own back-end processes to make calls to the API. Front-end clients (like apps and web browsers) must not be used to execute AlphaTouch API calls. Using front-end technologies to make AlphaTouch API calls will, in most cases, cause your API Key to be visible to the user, which is a gigantic security no-no. Integrators who wish to utilize front-end technologies must develop their own APIs to act as a middle man. For example, if an integrator needs to use JavaScript/Ajax to make an AlphaTouch API call, they must instead create an API on their own server which utilizes the API Key on the back-end to perform AlphaTouch API Calls and return the results to the user's browser. The idea is that back-end server should be used to synchronize data (through API Calls and Webhooks) so that individual clients are not constantly accessing our API on the fly.