Data API

Ideal for applications that can emit metrics and logs directly or for custom monitoring

This guide provides detailed information on using the slaOS direct data ingestion API (Data API). It covers authentication, request format, field descriptions, and best practices for submitting data to slaOS.

Need help troubleshooting the Data API? Contact us at [email protected] for consultation.

Ingestion Endpoint

To send events to slaOS, you need to use the following endpoint:

https://api.rated.co/v1/ingest/{ingestion_id}/{ingestion_key}

Understanding ingestion_id and ingestion_key

• ingestion_id: A unique identifier for your slaOS project. This value is specific to your organization and is used to identify the source of the data being ingested.

• ingestion_key: A secret key that is also specific to your organization and tied to your data ingestion activities. This key works in tandem with the ingestion_id to authenticate your data submissions.

To find the Ingestion Key and ID in the UI, navigate to Settings and then select General (Organization). You can access this by going to this link.

It’s important to note that the ingestion_key is not an API key or bearer token—it does not provide access to other slaOS functionalities and cannot be used to retrieve or manipulate data outside of the ingestion endpoint.

Additional security Considerations

1. Refreshing the Ingestion Key: You can refresh your ingestion key through the slaOS UI if you suspect it has been compromised (Settings -> General)

2. HTTPS: Always use HTTPS to encrypt data in transit.

Request Format

The API accepts JSON payloads. Here's an example of a valid request:

Single event

{
  "organization_id": "cust_12345",
  "key": "api_requests",
  "timestamp": "2024-08-15T10:30:45Z",
  "values": {
    "status_code": 200,
    "response_time": 0.145
  },
  "idempotency_key": "req_abc123"
}

Batch event

[
  {
    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": "2024-08-15T10:30:45Z",
    "values": {
      "status_code": 200,
      "response_time": 0.145
    },
    "idempotency_key": "req_abc123"
  },
  {
    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": "2024-08-15T10:31:45Z",
    "values": {
      "status_code": 200,
      "response_time": 0.45
    },
    "idempotency_key": "req_def456"
  }
]

The API accepts JSON payloads where the body can include either a single event or a list of events.

Field Descriptions

1. organization_id (string, required)

   • Unique identifier for the customer or vendor associated with this event.

   • See Prerequisites for a refresher of the different uses of organization_id.

2. key (string, required)

   • A unique identifier for the type of event or metric being recorded.

   • This is not a service name, but rather a metric identifier. You can have multiple metrics for a single service, product, or project.

   • Example: "api_requests", "database_queries", "order_processing"

3. timestamp (string, required)

   • The time the event occurred.

   • Accepted formats:

     • ISO 8601: YYYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z or [±]HH[:]MM]

     • Unix timestamp (as a string)

4. values (object, required)

   • Key-value pairs representing the metrics for this event.

   • Keys are metric names, values are the corresponding measurements.

   • Value types are dynamically derived from the first payload sent under the same key. However, only timestamps, strings, floats, and integers are supported.

5. idempotency_key (string, optional)

   • Idempotency key, a unique identifier for this specific event.

   • Used for deduplication if the same event is sent multiple times.

Limitations

• The total size of each event payload should not exceed 200KB.

• There are no specific restrictions on the number or types of key/value pairs in the values object.

Ingestion endpoint example

cURL

curl -X POST https://your-slaos-domain.com/v1/ingest/61dcde60-f40a-4a55-a303-911f2c2c4def/n3K9y3NiaOXVnw6deLQ5AQ \
     -H 'Content-Type: application/json' \
     -d '{
       "organization_id": "cust_12345",
       "key": "api_requests",
       "timestamp": "'"$(date -u +"%Y-%m-%dT%H:%M:%SZ")"'",
       "values": {
         "status_code": 200,
         "response_time": 0.145
       },
       "local_identifier": "req_abc123"
     }'

Python

import httpx
import json
from datetime import datetime

url = "https://your-slaos-domain.com/v1/ingest/your-ingestion-id/your-ingestion-key"
payload = {
    "organization_id": "cust_12345",
    "key": "api_requests",
    "timestamp": datetime.utcnow().isoformat() + "Z",
    "values": {
        "status_code": 200,
        "response_time": 0.145
    },
    "local_identifier": "req_abc123"
}

headers = {"Content-Type": "application/json"}

with httpx.Client() as client:
    response = client.post(url, json=payload, headers=headers)
    print(f"Status Code: {response.status_code}")
    print(f"Response: {response.text}")

TS/JS

import fetch from 'node-fetch';

const url = 'https://your-slaos-domain.com/v1/ingest/your-ingestion-id/your-ingestion-key';
const payload = {
    organization_id: 'cust_12345',
    key: 'api_requests',
    timestamp: new Date().toISOString(),
    values: {
        status_code: 200,
        response_time: 0.145
    },
    local_identifier: 'req_abc123'
};

const headers = { 'Content-Type': 'application/json' };

fetch(url, {
    method: 'POST',
    body: JSON.stringify(payload),
    headers: headers
})
.then(response => response.text())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Best Practices and Considerations

1. Consistency in key usage: Use consistent key values for similar types of events to ensure proper aggregation and analysis in slaOS.

2. Timestamp accuracy: Ensure that the timestamp is as accurate as possible to the time the event occurred.

3. Deduplication: Use the local_identifier field to prevent duplicate event processing if you're unsure about the success of a previous submission.