REST API temelleri

Bu sayfa, yönetim REST API’sinin izlediği kuralları açıklar. Rotaların kendisi, sayfanın sonunda bağlantısı verilen başvuru sayfalarında alanlarına göre listelenmiştir.

Yollar

Her yönetim yolu kuruluşunuzla sınırlandırılmıştır:

https://<your host>/tenant/<tenantId>/api/<resource>

Başvuru sayfalarında yollar /api/... ile başlayacak şekilde yazılır; önüne /tenant/<tenantId> eklenir. Örneğin /api/iot/devices, https://<your host>/tenant/<tenantId>/api/iot/devices anlamına gelir.

Her çağrıda Authorization: Bearer <API key> gönderin. Bkz. Kimlik doğrulama.

İstekler

Gövdeler JSON’dur: Content-Type: application/json gönderin. Tek istisna, multipart/form-data olan yazılım yüklemesidir.
Çoğu gövde katıdır: rotanın tanımadığı bir alan 400 ile reddedilir, sessizce yok sayılmaz. Doğru görünen bir alan için 400 aldığınızda yazımı kontrol edin.
PATCH yalnızca gönderdiğiniz alanları değiştirir. PUT bütünü değiştirir (bir profilin alarm kuralları, bir yerleşim veya bir ayar bölümü).
Alan boş değer kabul ediyorsa, null olarak ayarlanan alan temizlenir.
Kimlikler UUID’dir (6f1c0a2e-…). Yolda hatalı biçimli bir kimlik genellikle 400 veya 404 döner.

Yanıtlar

Yanıtlar JSON’dur. Tek bir kayıt, adıyla sarılmış gelir: { "device": {...} }, { "alarm": {...} }.
Bir liste, dizi ve toplam sayı olarak gelir. Dizinin adı rotaya göre değişir: { "devices": [...], "total": 42 }, { "items": [...], "total": 7 } veya { "data": [...], "total": 3 }. Her başvuru sayfası adı gösterir.
Bir gizli anahtar içeren yanıt (yeni bir cihaz belirteci, yeni bir API anahtarı, bir webhook imzalama sırrı) Cache-Control: no-store ile gönderilir ve sır yalnızca burada görünür.

Zamanlar

İki biçim kullanılır. Her başvuru sayfası hangisinin kullanıldığını belirtir.

Biçim	Nerede	Örnek
ISO 8601 metni, UTC	Kayıt alanları (`createdAt`, `lastActivityAt`), çoğu filtre, webhook yükleri	`"2026-11-05T10:00:00.000Z"`
1 Ocak 1970’ten itibaren geçen milisaniye, UTC	Telemetri (`ts`, `from`, `to`), alarm zamanları (`startTs`, `openedAt`)	`1762336800000`

createdFrom=2026-10-01&createdTo=2026-10-15 biçimindeki tarih aralığı filtreleri, UTC’de tam günleri alır, YYYY-MM-DD biçiminde, her iki gün de dahildir.

Listeler

Listeler sunucuda sayfalanır. İki sayfa stili vardır:

Stil	`page` başlangıcı	Kullanan (örnekler)
1 tabanlı	`1`	Cihazlar, cihaz profilleri, alarmlar, siteler ve varlıklar, API anahtarları, webhook’lar ve teslimatları
0 tabanlı	`0`	LoRaWAN ağ geçitleri ve cihazları, `page` ile bir cihazın komut geçmişi, cihaz ayar işleri ve temel çizgileri, MCP bağlı uygulamaları

Başvuru sayfaları her listenin tabanını verir. Ortak parametreler:

Parametre	Anlamı	Sınırlar
`page`	Sayfa numarası	listeye bağlı olarak 10.000 veya 100.000’e kadar
`pageSize`	Sayfa başına satır	varsayılan 20, en fazla 100 (bazı listeler belirtildiği gibi 200 veya 500’e izin verir)
`search`	Serbest metin, ad ve benzeri alanlarda eşleştirilir	en fazla 128 veya 200 karakter
`sort`	`field:asc` veya `field:desc`, en fazla üç, virgülle ayrılmış	yalnızca rotanın listelediği alanlar; diğerleri `400`
filters	Rotaya göre adlandırılmış	aşağıya bakın

Birkaç 0 tabanlı liste, eski istemciler için pageSize yerine limit ve search yerine q de kabul eder.

Sıralama

GET /api/iot/devices?sort=lastSeen:desc
GET /api/iot/lorawan/gateways?sort=status:asc,name:asc

Bilinmeyen bir alan 400 ile reddedilir, örneğin “Cannot sort by “x”. Sortable fields: name, connection, lastSeen, createdAt.” 0 tabanlı listelerde eşitlikler kimliğe göre çözülür, böylece sayfalama kararlı olur.

Filtreler

Tür	Biçim	Örnek
Bir kümeden biri	virgülle ayrılmış liste	`status=OPEN,ACKNOWLEDGED`
Kimlikler	virgülle ayrılmış UUID listesi, en fazla 100	`deviceId=…,…`
Bayrak	`true` veya `false`	`online=true`
Gün aralığı	`<name>From`, `<name>To`	`createdFrom=2026-11-01`
Sayı aralığı	`<name>Min`, `<name>Max`	rotanın sunduğu yerlerde

Bir parametreyi boş göndermek yerine çıkarın: çoğu liste boş parametreyi yok sayar, ancak bazıları reddeder.

Tüm sayfaları okumak

// Node.js 18+: read every device, 100 at a time (a 1-based list)
const base = `https://${host}/tenant/${tenant}/api/iot/devices`;
const all = [];
for (let page = 1; ; page++) {
  const res = await fetch(`${base}?page=${page}&pageSize=100&sort=createdAt:asc`, {
    headers: { Authorization: `Bearer ${key}` },
  });
  if (res.status === 429) { await new Promise((r) => setTimeout(r, Number(res.headers.get('Retry-After') ?? 60) * 1000)); page--; continue; }
  const { devices, total } = await res.json();
  all.push(...devices);
  if (all.length >= total || devices.length === 0) break;
}

Başkalarının değiştirdiği bir listede sayfalama yaparken, değişmeyen bir alana (createdAt) göre sıralayın.

Başkaları tarafından yapılan değişiklikler

Bazı yazma işlemleri, kaydı okuduğunuzdan beri değişmediğini denetler:

Nerede	Nasıl	Çakışmada
Cihaz profilleri	Profilin `version` değerini `PATCH` gövdesinde `expectedVersion` olarak gönderin	`409`, `details.reason` = `stale_profile`
Cihaz ayar bölümleri	Bölümün `ETag` değerini bir `If-Match` başlığında gönderin	`412`, `details.reason` = `rev_mismatch`; `If-Match` olmadan `428`

Bir profilin alarm kurallarında böyle bir denetim yoktur: PUT tüm kümeyi değiştirir, bu yüzden değiştirmeden hemen önce kuralları okuyun.

Yeniden okuyun, değişikliğinizi güncel kopyaya uygulayın ve yeniden gönderin.

Bulunamadı ve izin verilmedi

Başka bir kuruluşa ait ya da okuma izniniz olmayan bir kayıt, var olmayan bir kayıt gibi 404 döner. Hiç kullanma izniniz olmayan bir rota 403 döner. Hata gövdesi ve tüm durum kodları için bkz. Hatalar ve hız sınırları.

İzinler

Her rota ihtiyaç duyduğu izni belirtir; uygulamanın denetlediği izinle aynıdır. Başvuru sayfaları her rota için bunu listeler, örneğin iot_device.devices.read. Bir anahtara bu izni Modül izinleri bölümünde verin. Yalnızca Sahip rolünün sahip olduğu bir izin anahtara verilemez.

Rota başvuruları

Alan	Sayfa
Cihazlar, kimlik bilgileri, bağlantı, günlük, cihaz profilleri	Cihazlar ve profiller API’si
Son değerler, geçmiş, öznitelikler	Telemetri ve öznitelikler API’si
Komutlar ve komut kataloğu	Komutlar API’si
Alarmlar, alarm kuralları, sessize almalar	Alarmlar API’si
Siteler, varlıklar, yerleşim, ilişkiler	Siteler ve varlıklar API’si
Yazılım paketleri, dağıtımlar, cihaz ayarları	Yazılım ve cihaz ayarları API’si
LoRaWAN ağ geçitleri, cihazlar, eşleştirme, çerçeveler	LoRaWAN API’si
Webhook’lar	Webhook’lar
API anahtarları	Kimlik doğrulama
LoRaWAN kodekleri	Kodek API’si