RESTFul API Reference

This document provides a reference for all available API endpoints in the Zafron platform. Use the API to query for device's properties and sensor data.

Authentication

All API requests require authentication using an API key in the header:

x-api-key: YOUR_API_KEY

Devices

Get All Devices

GET /api/v1/devices

Retrieves a list of all devices for the authenticated user.

Responses

Status	Description
200	List of devices
401	Unauthorized - Invalid or missing API key
403	Forbidden - No API access permissions

Example Response (200 OK)

[
  {
    "id": "device123",
    "name": "Temperature Sensor",
    "description": "Office temperature sensor",
    "type": "sensor",
    "created_at": "2023-09-01T10:00:00Z",
    "last_seen": "2023-10-15T08:30:45Z",
    "metadata": {
      "location": "Main Office",
      "floor": "3"
    }
  }
]

Example Request

const fetchDevices = async () => {
  const API_KEY = 'your_api_key';
  
  try {
    const response = await fetch(
      'https://api.zafron.dev/api/v1/devices',
      {
        method: 'GET',
        headers: {
          'x-api-key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }
    
    const data = await response.json();
    console.log('Devices:', data);
    return data;
  } catch (error) {
    console.error('Error fetching devices:', error);
  }
};

Device Measurements

Get Device Measurements

GET /api/v1/devices/{id}/measurements

Retrieves measurements for a specific device within a given time range.

Parameters

Parameter	Type	In	Description
id	string	path	Device ID
start	date-time	query	Start date (ISO format)
end	date-time	query	End date (ISO format)
limit	integer	query	Maximum number of records (default: 100)

Responses

Status	Description
200	List of measurements
401	Unauthorized - Invalid or missing API key
403	Forbidden - No API access permissions
404	Device not found

Example Response (200 OK)

[
  {
    "id": "measurement123",
    "timestamp": "2023-10-11T15:22:44.123Z",
    "channel": 1,
    "type": "temperature", 
    "unit": "C",
    "value": 23.5,
    "metadata": {
      "rssi": -75,
      "snr": 9.2
    }
  }
]

Example Request

const fetchMeasurements = async () => {
  const API_KEY = 'your_api_key';
  const deviceId = 'device123';
  
  // Set query parameters
  const params = new URLSearchParams({
    start: '2023-10-01T00:00:00Z',
    end: '2023-10-15T23:59:59Z',
    limit: 50
  });
  
  try {
    const response = await fetch(
      `https://api.zafron.dev/api/v1/devices/${deviceId}/measurements?${params}`,
      {
        method: 'GET',
        headers: {
          'x-api-key': `${API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }
    
    const data = await response.json();
    console.log('Measurements:', data);
    return data;
  } catch (error) {
    console.error('Error fetching measurements:', error);
  }
};