API

Uygulamanın yaptığı her şeyi, doğrudan kullanabileceğiniz bir REST API üzerinden yapar. Toplu cihaz oluşturmak, kendi araçlarınızdan sağlama yapmak veya sayaçları kendi panelinize çekmek için kullanışlıdır.

Etkileşimli referans

Tam ve her zaman güncel tanım, API'nin kendisi tarafından sunulur:

Yerelde çalışırken bu localhost:3000/docs olur.

API'nin kendi kodundan üretilir; bu yüzden sunucunun gerçekte sunduğundan sapamaz. Her uç nokta bir özet, parametreleri, başarı yanıtı ve döndürebileceği hatalarla birlikte gelir. Tipli bir SDK için bir istemci üretecini /docs-json adresine yönlendirin.

Kimlik doğrulama

POST /auth/login, kimlik bilgilerinizle bir erişim belirteci ve bir yenileme belirteci döndürür. Erişim belirtecini diğer her istekte gönderin:

Authorization: Bearer <erişim belirteci>

Süresi dolduğunda POST /auth/refresh yenileme belirtecini yeni bir çiftle takas eder. POST /auth/logout simetri için vardır — API oturum durumu tutmaz, yani çıkış yapmak istemcinizin belirteçlerini atmasıdır.

Kiracı seçme

Hemen her uç nokta tek bir kiracının içinde çalışır; kiracı bir başlıkla belirtilir:

x-tenant-id: <kiracı uuid>

Kiracıya bağlı bir yolda bunu atlamak 400 verir. İstisnalar, kiracı almayan auth, health ve uç nokta (ingest) uçlarıdır.

GET /auth/me, belirtecinizin kullanabileceği kiracıları listeler.

Sayfalama

Liste uç noktaları page (1'den başlar) ve limit (1–100, varsayılan 20) alır:

GET /api/v1/devices?page=2&limit=50

ve veriyi sayaçlarıyla döndürür:

{
  "data": [ ... ],
  "meta": { "page": 2, "limit": 50, "total": 384, "totalPages": 8 }
}

Hatalar

Her hata için tek bir zarf; sabit bir code ile anahtarlanır. Bkz. Hata kodları.

Ayrıca istek gövdesindeki bilinmeyen özelliklerin yok sayılmadığını, reddedildiğini unutmayın — bu, sessiz bir yazım hatasını anında ve açık bir hataya dönüştürür.

Uç noktalar (ingest) farklıdır

ingest grubu, bir cihaz ağının POST ettiği genel sol taraftır. Üç şey onları ayırır:

1. Merkez belirteci yok. Her kaynak kendi yükünü adaptörü üzerinden doğrular. Bkz. Bir kaynak bağlayın.
2. Yalnızca JSON değil. application/json, application/xml, text/xml ve text/plain kabul edilir, 1 MB'a kadar.
3. İkisi API önekinin dışındadır. POST /i/{slug} ve POST /i/s/{slug} alan adının kökünde durur; böylece başkasının konsoluna yapıştırdığınız bağlantı kısa kalır.

Uygulamadan önce planlayın

Sağlama uç noktaları çiftler hâlinde gelir. plan sürümü bir kuru çalışmadır: sağlayıcıya gönderilecek istekleri tam olarak döndürür ve hiçbir şeyi değiştirmez. apply sürümü onları gönderir, kurulum yapılandırmasıyla kapatılabilir ve idempotenttir — yeniden çalıştırmak çoğaltmaz, uzlaştırır.

Betiklerden de önce plan çağırın ve döndürdüğünü günlüğe yazın. Elde edebileceğiniz en ucuz denetim izidir.

Sırada