HTTP API

RTLS sunucusu, uygulama sunucuları ile iletişim için HTTP protokolünü kullanır. Tüm istek ve yanıt gövdelerinde veri serializasyonu için JSON formatı kullanılır.

Olay Tanımlayıcıları

Her olay, UUID v4 formatında benzersiz bir id alanına sahiptir. Bu tanımlayıcılar, olayların tekil olarak referanslanmasını ve SSE akışında belirli bir noktadan devam edilmesini sağlar.

Örnek: "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"

Endpointler

GET /events

Olayları sorgulamak ve akış halinde almak için kullanılır. Bu endpoint iki farklı modda çalışır:

Standart REST Yanıtı

Basit bir GET isteği ile mevcut olayları JSON dizisi olarak döndürür.

GET /events

Yanıt:

[
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "UWBRangingCompleted",
    "timestamp": 1704067200000,
    ...
  }
]

Filtreleme

Olaylar, sorgu parametreleri kullanılarak filtrelenebilir. Birden fazla filtre aynı anda kullanılabilir.

GET /events?type=LocationCalculated&tagId=tag-001
GET /events?anchorId=anchor-005
GET /events?type=IMUEventDetected&type=EmergencyButtonPressed

Filtre Parametreleri:

Parametre	Tip	Açıklama
type	string	Olay türüne göre filtreler. Birden fazla type parametresi verilebilir.
tagId	string	Belirli bir tag'e ait olayları filtreler.
anchorId	string	Belirli bir anchor'a ait olayları filtreler.

SSE (Server-Sent Events) Akışı

Olayları gerçek zamanlı olarak akış halinde almak için SSE kullanılır. İstemci, Accept: text/event-stream başlığını göndererek SSE modunu aktif eder.

GET /events
Accept: text/event-stream

Başlangıç ID'si belirtilerek belirli bir noktadan itibaren olaylar alınabilir:

GET /events?start_id=f47ac10b-58cc-4372-a567-0e02b2c3d479
Accept: text/event-stream

SSE modunda da filtreleme parametreleri kullanılabilir:

GET /events?type=LocationCalculated&tagId=tag-001
Accept: text/event-stream

SSE Yanıt Formatı:

id: f47ac10b-58cc-4372-a567-0e02b2c3d479
data: {"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "type": "LocationCalculated", "timestamp": 1704067200000, ...}

id: a1b2c3d4-5678-4321-abcd-ef0123456789
data: {"id": "a1b2c3d4-5678-4321-abcd-ef0123456789", "type": "UWBRangingCompleted", "timestamp": 1704067200100, ...}

Parametreler:

Parametre	Tip	Zorunlu	Açıklama
start_id	string	Hayır	Bu ID'den (UUID) itibaren olayları akışa başlatır.

---

POST /commands

Tag'lere veya anchor'lara komut göndermek için kullanılır.

POST /commands
Content-Type: application/json

İstek Gövdesi:

{
  "type": "SetUWBConfig",
  "tagId": "tag-001",
  ...
}

Yanıt:

{
  "success": true,
  "message": "Komut başarıyla gönderildi"
}

---

Webhook (Push Mode)

RTLS sunucusu, olayları uygulama sunucusuna aktif olarak iletmek için webhook mekanizmasını kullanır. Webhook yapılandırıldığında, olaylar belirtilen URL'ye toplu (batch) olarak HTTP POST istekleri ile gönderilir.

Olaylar her zaman bir JSON dizisi olarak gönderilir. Tek bir olay olsa bile dizi formatı korunur.

Metod: POST

İçerik Tipi: application/json

İstek Gövdesi:

[
  {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "UWBRangingCompleted",
    "timestamp": 1704067200000,
    "anchorId": "anchor-001",
    "tagId": "tag-001",
    "distance": 5.23
  },
  {
    "id": "a1b2c3d4-5678-4321-abcd-ef0123456789",
    "type": "BLEAdvertisementReceived",
    "timestamp": 1704067200050,
    "anchorId": "anchor-002",
    "tagId": "tag-001",
    "rssi": -65
  }
]

Uygulama sunucusu, webhook isteğini başarıyla aldığı durumlarda 200 OK yanıtı dönmelidir.

---

Olay ve Komut Referansı

Desteklenen olay türleri için events/ dizinine, desteklenen komut türleri için commands/ dizinine bakınız. Her olay ve komut için ayrıntılı açıklama ve JSON şeması ilgili dizinlerde yer almaktadır.