Sending Data to ControlCom Connect via HTTP

In addition to MQTT, ControlCom Connect provides an HTTP API for sending data from your devices. This method is particularly useful for devices that cannot maintain persistent connections or when you need to integrate with systems that prefer HTTP communication.

API Endpoint

To send data to ControlCom Connect via HTTP, use the following endpoint:

https://<endpointUrl>/payload

Replace organizationId with your actual organization ID.

Authentication

Authentication is performed using API key credentials passed as query parameters:

• apiKeyId: Your API key ID
• apiKeySecret: Your API key secret

These credentials can be generated in the ControlCom Connect interface under Administration > API Keys.

Payload Format

The HTTP API accepts JSON payloads with the following structure:

{
  "organizationId": "organizationId",
  "deviceId": "deviceId",
  "dataArray": [
    {
      "key": "temperature",
      "value": 24.5
    },
    {
      "key": "humidity",
      "value": 65
    }
  ]
}

The structure follows this interface:

{
  organizationId: string;  // Your organization ID
  deviceId: string;        // The device ID sending the data
  dataArray: {
    key: string;                      // Variable name
    value: string | number | boolean; // Variable value
    timestamp?: number;               // Optional: Unix timestamp in milliseconds
  }[];
}

If timestamp is omitted for any item, the current server time will be used when the message is received.

Code Examples

const axios = require('axios');

const API_ENDPOINT = 'https://<endpointUrl>/payload';
const API_KEY_ID = 'your-api-key-id';
const API_KEY_SECRET = 'your-api-key-secret';
const ORGANIZATION_ID = 'your-organization-id';
const DEVICE_ID = 'your-device-id';

async function sendData() {
  try {
    const response = await axios.post(
      `${API_ENDPOINT}?apiKeyId=${API_KEY_ID}&apiKeySecret=${API_KEY_SECRET}`,
      {
        organizationId: ORGANIZATION_ID,
        deviceId: DEVICE_ID,
        dataArray: [
          {
            key: 'temperature',
            value: 24.5,
            timestamp: Date.now() // Optional: current time in milliseconds
          },
          {
            key: 'humidity',
            value: 65
          }
        ]
      }
    );
    
    console.log('Data sent successfully:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error sending data:', error.response ? error.response.data : error.message);
    throw error;
  }
}

sendData();

Best Practices

When sending data to ControlCom Connect via HTTP, follow these best practices:

Security

• Keep your API keys secure and never expose them in client-side code
• Rotate API keys periodically
• Use HTTPS for all API calls
• Consider using environment variables to store API credentials

Performance

• Batch multiple data points in a single request when possible
• Implement retry logic with exponential backoff for failed requests
• Consider connection pooling for high-frequency data transmission

Error Handling

• Implement proper error handling for different HTTP status codes
• Log detailed error information for troubleshooting
• Set appropriate request timeouts
• Implement circuit breaker patterns for unreliable connections

Data Management

• Use consistent variable names across requests
• Include timestamps for time-sensitive data
• Validate data before sending
• Consider data compression for large payloads

By following these guidelines, you can ensure reliable data transmission to ControlCom Connect from your devices using the HTTP API.

For information on sending data using MQTT, see our MQTT Integration Guide.