What is Enterprise API and how to use it

Who can access the Enterprise API

We provide access to the Enterprise API to extensive security and service companies already serving or planning to serve thousands of Ajax security systems. Such companies have developed IT infrastructure and resources to ensure the integration of our products and understand that the company accepts responsibility for providing a positive experience associated with the Ajax security systems.

What I need to know before start

Enterprise API architecture uses server-to-server communication. Server-to-server (S2S) is an extension of the client-server computer network protocol design, where servers directly exchange data with other servers.

There are two parts of the integration process with the Enterprise API:

1. Establishing synchronous communication with the Ajax Cloud.
   Synchronous API calls allow you to control the Ajax security systems and modify its settings. In the case of synchronous communication, Enterprise API returns data for requests either immediately or at a later time, respectively. Therefore, your server requests data and waits for it until a value is returned.
2. Implementing asynchronous workflows with Amazon SQS. Amazon Simple Queue Service (SQS) is a distributed message-queuing service supporting the programmatic sending and receiving messages via web service applications. Follow this link to learn more.

Asynchronous requests are used to retrieve security system events from the Amazon SQS, which is part of the Enterprise API architecture.

The diagram below illustrates how the partner environment interacts with Ajax Cloud via Enterprise API.

Once there is an event notification generated by the registered security system, it is immediately available for retrieving from the Ajax integration SQS queues.

With the Amazon SQS API and Amazon SDKs, you can configure your API client to initiate calls for receiving new messages only when they are ready, eliminating unnecessary API requests. Therefore, it does not tie up your application or server resources waiting on a request.

How to start to use Enterprise API

Request access

Required information, technical documents, and access to the Enterprise API interface are available upon request of the security or service company. If you are interested in making the most of the features of the Ajax products, fill out the form.

Save your Enterprise API and AWS access keys

Once your request has been approved, you’ll receive the following credentials in an email message from our team:

• Ajax’s integration ID. This is an automatically generated unique identifier of your API account. It is also used in your Enterprise API key and events queue name.
• X-API-Key. This is a unique identifier that you will use to authenticate all requests to the Enterprise API.
• AWS access key ID. This key is used to sign the requests you send to Amazon SQS.
• AWS secret access key. Access Key ID and AWS secret access key are used for programmatic (API) access to Amazon SQS.
• Events queue. This is the name of your Events queue. It is used for storing alerts and events of the Ajax security system.
• API Endpoint. This is essentially a base URL to which the Enterprise API endpoint paths are appended.

Please, keep this data secure. Don’t disclose your credentials to anyone. Sharing your account credentials with other people make your account more vulnerable to sniffing/phishing attempts.

Set up your access and make your first request

First, you need to log in to the Enterprise API by calling this API endpoint. After this, to start work with the Ajax security system, you need to add it to your Ajax account. Once you have access to the security system, you are ready to use the Enterprise API.

Please note that PRO accounts (if you use Ajax PRO or PRO Desktop apps) are not supported. You can send API requests only with a user account (if you use Ajax Security System app).

Synchronous calls in ​​Enterprise API

Synchronous Enterprise API calls are organized around REST. They have predictable resource-oriented URLs, accept form-encoded and raw request bodies, return JSON-encoded responses. It uses standard HTTP response codes, authentication, and verbs. A list of the Enterprise API calls is available here.

The documentation shows the HTTP method, path, resource, and parameters appended to the base URL (API Endpoint) to form a request.

The following HTTP methods (verbs) are available:

• GET. Uses for retrieving resources.
• POST​. Uses for creating resources.
• PUT. Uses for replacing resources or entire collections. Fields will be replaced with given values. Any fields without given values will be reset to their default. Any fields without defaults, for example, ID fields, will remain unchanged.
• DELETE​. Uses for deleting resources.

Authentication in Enterprise API

Enterprise API uses X-API-Key and Session Token to authenticate requests. A session token is produced after successful login and should be used for all consequent user-initiated operations.

A session token expires in 15 minutes. Refresh operation (/refresh) should be used when the session token has expired. It allows keeping the user session authenticated for a more extended period without re-login. The operation should be performed with a long-lived (30 days) refresh token with /login response. The server responds with a new session token and refresh token and invalidates the old pair. If the session token is still valid, it becomes invalidated after the refresh. Use this API call to refresh the session token.

If you do not include your API key and session token when making an API request or use incorrect or outdated ones, the Ajax Cloud server will return an error.

Enterprise API requests should be sent over HTTPS. Calls over HTTP are not supported, as well as requests without authentication.

Rate limits in Enterprise API

Ajax Cloud server has rate limits to maintain performance and stability for all Enterprise API clients.

API endpoints have a limit of 100 API calls per minute for a single API key. Be aware of this limitation when you are running any batch process against the API. If you reach a rate limit, the Ajax Cloud server will respond with a 429 status code (Too many requests).

Errors in Enterprise API

Enterprise API uses HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error (e.g., omitted required parameter, etc.). Codes in the 5xx range indicate an error with the Ajax Cloud server.

List of possible errors:

Every error response should be a valid JSON object, predefined structure, and application/JSON type. Please, find below an example of an error response body:

Response object specification:

Error object specification:

Error code specification:

Asynchronous calls

One of the essential parts of the Enterprise API architecture is Amazon SQS. We use it for sending Ajax security system events to the partners’ servers.

Amazon SQS is a message queuing service that decouples the components of a cloud application. It can transmit any volume of data, at any level of throughput, without losing messages or requiring other services to be always available. That is, you can retrieve event messages from SQS asynchronously at your system or application pace. SQS is built on the concept of a Point-to-Point intersystem messaging model. SQS provides a simple HTTP API that is easy to implement using the AWS SDKs.

Point to Point is when a message(s) is sent from one app (producer or sender) to another (consumer/receiver) via a queue. There can be more than one consumer listening to a queue, but only one of them will get the message. Hence, it is Point to Point or One to One.

SQS mechanics

Ajax Events queue is implemented as SQS FIFO type queue. The order in which events messages are sent by the Ajax Cloud server and received by the Partner server is strictly preserved. It is crucial for forming a coherent series of events generated by the Ajax security system devices.

FIFO (First-In-First-Out) queues are designed to enhance messaging between apps when the order of operations and events is critical, or duplicates can’t be tolerated.

Learn more

To retrieve messages from the SQS queue, you need to poll them. AWS SQS is a poll-based service, that’s meaning SQS will not send messages to your app. Thus, your app needs to poll messages from the SQS queue.

There are two types of polling mechanisms supported by Amazon SQS for consuming messages: Short Polling and Long Polling.

While the regular short polling returns immediately, long polling does not return a response until a message arrives in the message queue, or the long poll times out. The maximum value of a long-poll timeout is 20 seconds. AWS SDKs work with 20-second long polls by default.

Long polling is preferred to use. Long polling requests let you receive messages promptly and, at the same time, reduce the number of empty responses returned.

But there might be exceptions. E.g., if your app uses a single thread to poll both Ajax events and any other queue. In this case, long polling will not be the best choice since it can delay processing another queue that might contain messages. In such cases, it is recommended to use a single thread for processing each queue.

Accessing SQS

Amazon SQS requires credentials to authenticate your requests. Use your access keys (AWS access key ID and AWS secret access key) to access the SQS through SDK or AWS CLI.

To send events to the SQS queue, log in to the Enterprise API and add the hub to your account via the Ajax app. Also, you can add the hub by initiating create a hub to user binding API call.

Ajax’s events queue is available in Europe (Ireland) AWS infrastructure region. The code of the region is eu-west-1.

Receiving messages

Amazon SQS does not automatically delete the message. It means that after receiving the message, it remains in the queue. Thus, you must delete the message during a visibility timeout parameter from the queue after receiving and processing. The default visibility timeout for the Ajax events queue is 30 seconds.

If your system does not call the DeleteMessage action before the visibility timeout expires, this message becomes available for retrieving and is received again. Please, note, as long as you do not delete the earlier message, subsequent ones will not be delivered.

To send a receive message request, initiate the ReceiveMessage API action. Follow these links for detailed information:

To send a delete message request, initiate the DeleteMessage API action. Follow these links for detailed information:

Data transfer model

Event messages in Ajax events queue have application/json type. Please, find an example below:

The event specification:

Event type specification.

The event data transfer models are also defined on the Ajax API page in the Models section.

Code examples of retrieving messages from Amazon SQS

This paragraph provides examples of subscribing to Amazon SQS using AWS SDK for Java and Amazon SQS Java Messaging Library (JMS). To build and run these examples, you need Apache Maven v3.0 and higher, as well as Java SE Development Kit.

Example of building the message receiver application using AWS Java library for Amazon SQS

To do this:

1. Import the latest library to your project from the Maven repository. You might also need to add the aws-java-sdk-core library as a dependency either.

   pom.xml

   <!– https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-sqs –><dependency>    <groupId>com.amazonaws</groupId>    <artifactId>aws-java-sdk-sqs</artifactId>    <version>_version_</version></dependency>
2. Import this code snippet to your project to start receiving messages.

   TestMessageReceiver.java

   public class TestMessageReceiver {    public static void main(String[] args) {        String region = “eu-west-1”;        // TODO: Specify correct SQS queue name        String queueName = “ajax-<name>-events-demo.fifo”;         // Creating credentials from accessKey/secretKey pair        // Use accessKey/secretKey values provided by AJAX Team        BasicAWSCredentials credentials = new BasicAWSCredentials(                “accessKey”,                “secretKey”        );         AWSStaticCredentialsProvider credentialsProvider = new AWSStaticCredentialsProvider(credentials);        AmazonSQS sqs = AmazonSQSClientBuilder.standard()                .withCredentials(credentialsProvider)                .withRegion(region)                .build();         // Getting queueUrl to connect        String queueUrl = sqs.getQueueUrl(queueName).getQueueUrl();        while (true) {            ReceiveMessageRequest receiveRequest = new ReceiveMessageRequest(queueUrl)                    .withMaxNumberOfMessages(10)                    .withWaitTimeSeconds(20);             List<Message> messages = sqs.receiveMessage(receiveRequest).getMessages();             if (messages.isEmpty()) {                continue;            }             System.out.println(“Received messages: “ + messages);             // Deleting received and processed messages from the queue            List<DeleteMessageBatchRequestEntry> deleteEntries = messages.stream()                    .map(message -> new DeleteMessageBatchRequestEntry(message.getMessageId(), message.getReceiptHandle()))                    .collect(Collectors.toList());             DeleteMessageBatchRequest deleteRequest = new DeleteMessageBatchRequest(queueUrl)                    .withEntries(deleteEntries);            List<BatchResultErrorEntry> failed = sqs.deleteMessageBatch(deleteRequest).getFailed();             // Checking if there is any issue with deleting messages            if (!failed.isEmpty()) {                System.out.println(“Failed to delete next messages: “ + failed);            } else {                System.out.println(“Successfully deleted all the messages.”);            }        }    }}
3. Run your app to start. Additionally, please find below a code snippet that transforms the JSON payload into the Java object.

   MessageDeserialize

   ObjectMapper objectMapper = new ObjectMapper()        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); sqs.receiveMessage(receiveRequest).getMessages().forEach(message -> {    try {        IntegrationEvent event = objectMapper.readValue(message.getBody(), IntegrationEvent.class);        System.out.println(“Received event: “ + event);    } catch (Exception e) {        System.out.println(“Failed to process message “ + e);    }});

Example of building the message receiver application using the Amazon SQS JMS library

To do this:

1. Import the latest library to your project from the Maven repository. You might also need to add the aws-java-sdk-core library as a dependency either.

   pom.xml

   <!– https://mvnrepository.com/artifact/com.amazonaws/amazon-sqs-java-messaging-lib –><dependency>    <groupId>com.amazonaws</groupId>    <artifactId>amazon-sqs-java-messaging-lib</artifactId>    <version>_version_</version></dependency>
2. Import this code snippet to your project to start receiving messages.

   TestMessageReceiver.java

   public class TestJmsMessageReceiver {    public static void main(String[] args) throws Exception {        String region = “eu-west-1”;        // TODO: Specify correct queue name        String queueName = “ajax-<name>-events-demo.fifo”;         // Creating credentials from accessKey/secretKey pair        // Use accessKey/secretKey values provided by AJAX Team        BasicAWSCredentials credentials = new BasicAWSCredentials(                “accessKey”,                “accessKey”        );        AWSStaticCredentialsProvider credentialsProvider = new AWSStaticCredentialsProvider(credentials);        SQSConnectionFactory connectionFactory = new SQSConnectionFactory(                new ProviderConfiguration(),                AmazonSQSClientBuilder.standard()                        .withCredentials(credentialsProvider)                        .withRegion(region)        );         SQSConnection connection = connectionFactory.createConnection();        Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);        Queue queue = session.createQueue(queueName);        MessageConsumer consumer = session.createConsumer(queue);         consumer.setMessageListener(message -> System.out.println(“Received message: “ + message));         connection.start();    }}
3. Run your app to start. Additionally, please find below a code snippet that transforms the JSON payload into the Java object.

   JmsMessageDeserialize

   ObjectMapper objectMapper = new ObjectMapper()        .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false); consumer.setMessageListener(message -> {    try {        if (message instanceof TextMessage) {            String payload = ((TextMessage) message).getText();            IntegrationEvent event = objectMapper.readValue(payload, IntegrationEvent.class);                         System.out.println(“Received event: “ + event);        }    } catch (Exception e) {        System.out.println(“Failed to process message “ + e);    } });

Event codes

Please, find below examples of event codes translation for English localization in JSON format. Note, we can provide translations in a big variety of languages and formats. Contact your Ajax manager for futher support.

Example: “M_01_20”: “%3$s: open, %1$s in %2$s”,

Placeholders:

• M — signal type. The static parameter.
• 01 — device type. Learn more in Device Type.
• 20 — event signal “open”. The description is contained in each event.
• %3 — hub name.
• %1 — event source object name (e.g., detector name).
• %2 — event room name.

Device types

Please, find below list of device numbers that form an event code.

Additional resources