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:

POST https://api.controlcomtech.com/data/v1/organizations/<organizationId>/devices/<deviceId>

Replace organizationId with your actual organization ID.

Replace deviceid with your actual device ID.

Authentication

Authentication is performed using API key credentials passed in the Authorization Header in the form of Basic credentials.

Authentication can also be performed by using the User JSON Web Token in the Authorization in the form of Bearer credentials.

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

Creating Basic credentials using API Keys

Create the properly encoded Basic credentials Note Most libraries like NodeJS axios handle the encoding part for you. See code examples.

  # MacOS / linux
  echo "myApiKeyId:myApiKeySecret" | base64
  # Outputs bXlBcGlLZXlJZDpteUFwaUtleVNlY3JldAo=

After generating, add the keyword Basic in front to have a fully valid Basic credential Authorization header.

Basic bXlBcGlLZXlJZDpteUFwaUtleVNlY3JldAo=

Payload Format

The HTTP API accepts JSON payloads with the following structure:

{
  "data": [
    {
      "key": "temperature",
      "value": 24.5,
      "timestamp": 1763123411086
    },
    {
      "key": "humidity",
      "value": 65,
      "timestamp": 1763123411086
    }
  ]
}

The structure follows this interface:

{
  data: {
    key: string;                      // Variable name
    value: string | number | boolean; // Variable value
    timestamp: number;                // Unix timestamp in milliseconds
  }[];
}

Code Examples

const axios = require('axios');

const API_ENDPOINT = 'https://api.controlcomtech.com/data/v1/organizations';
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 nowInMs = Date.now() // current time in milliseconds
    const response = await axios.post(
      `${API_ENDPOINT}/${ORGANIZATION_ID}/devices/${DEVICE_ID}`,
      {
        data: [
          {
            key: 'temperature',
            value: 24.5,
            timestamp: nowInMs
          },
          {
            key: 'humidity',
            value: 65,
            timestamp: nowInMs
          }
        ]
      },
      {
        auth: {
          username: API_KEY_ID,
          password: API_KEY_SECRET
        }
      }
    );
    
    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.