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"

Olay tanımlayıcıları RTLS sunucusu tarafından üretilir. Anchor'lar olay gönderirken id alanı kullanmaz; ayrıntı için arsp/README.md.

Kimlik Doğrulama

Uygulama sunucusu yüzünde kimlik doğrulaması isteğe bağlıdır ve yapılandırma ile etkinleştirilir. Etkinken, anchor yüzündekiyle aynı biçim kullanılır:

Authorization: Bearer <anahtar>

Uygulama sunucusu anahtarı, anchor anahtarlarından bağımsızdır; biri diğerinin yerine kullanılamaz.

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.

Aynı parametrenin birden fazla değeri VEYA, farklı parametreler ise VE ile birleşir. Örneğin ?type=A&type=B&tagId=t1, "(tür A veya B) ve tag t1" anlamına gelir.

Sayfalama

Yanıt boyutunu sınırlamak için limit ve start_id birlikte kullanılır.

Parametre	Tip	Açıklama
limit	integer	Döndürülecek en fazla olay sayısı. Sunucu tarafında bir tavan uygulanır.
start_id	string	Bu ID'den sonraki olaylardan başlar. Bilinmeyen bir ID 400 ile reddedilir.

Olaylar her zaman sunucuya ulaşma sırasına göre döner. Sonraki sayfa, son olayın id değeri start_id olarak verilerek alınır:

GET /events?limit=100
GET /events?limit=100&start_id=<son olayın id değeri>

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 sonraki olaylardan itibaren akışa başlar.

Yeniden Bağlanma (Last-Event-ID):

SSE istemcileri bağlantı koptuğunda, en son aldıkları olayın ID'sini standart Last-Event-ID başlığı ile otomatik olarak gönderir. Sunucu bu başlığı start_id gibi değerlendirir; böylece tarayıcı tarafında ek kod yazmadan kesintisiz devam sağlanır.

GET /events
Accept: text/event-stream
Last-Event-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479

İki imleç arasındaki farklar:

Kaynak	Bilinmeyen ID durumunda davranış
start_id	400 döner. Açık bir istek olduğu için hata bildirilir.
Last-Event-ID	Akış güncel imleçten sürdürülür. Otomatik yeniden bağlanmanın kalıcı olarak kırılmaması içindir.

Her ikisi de verilirse start_id önceliklidir.

Akış Sırası:

Bağlantı kurulduğunda sunucu önce imleçten sonraki mevcut olayları veritabanından gönderir, ardından canlı akışa geçer. Bu geçişte olay kaybı ya da tekrarı olmaz.

---

POST /commands

Not: Bu uç nokta henüz uygulanmamıştır. Aşağıdaki tanım hedef sözleşmedir.

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)

Not: Webhook desteği henüz uygulanmamıştır. Aşağıdaki tanım hedef sözleşmedir. Şu an için olaylar GET /events üzerinden REST veya SSE ile çekilir (Pull 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.

---

Uygulama Durumu

docs/ dizini hedef API sözleşmesini tanımlar. Sunucunun (rtlsd) mevcut sürümünde uygulanmış olan bölümler aşağıdadır.

Özellik	Durum
GET /events — REST ve filtreler	Uygulandı
GET /events — SSE akışı ve devam etme	Uygulandı
UWBRangingCompleted olayı	Uygulandı
Diğer olay türleri	Uygulanmadı
POST /commands	Uygulanmadı
Webhook (Push Mode)	Uygulanmadı