Integrasi backend dengan perangkat keras berdaya rendah (low-power IoT) seperti layar e-ink (misalnya TRMNL) memiliki kendala arsitektural yang berbeda dari klien web modern. Mikrokontroler beroperasi dengan siklus deep sleep, kapasitas RAM terbatas, dan radio Wi-Fi yang menguras baterai jika aktif terlalu lama. Kontrak API webhook untuk kategori perangkat ini harus deterministik, hemat bandwidth, dan meminimalkan waktu komputasi perangkat.

1. Header Autentikasi: Preshared API-Key

Penggunaan alur OAuth2 atau rotasi token berbasis refresh token membebani memori mikrokontroler dan memperpanjang durasi koneksi radio. Pendekatan standar yang paling efisien adalah preshared token statis yang dikirimkan melalui HTTP header kustom.

GET /api/v1/display/poll HTTP/1.1
Host: api.example.com
User-Agent: TRMNL-Device/1.0.4 (ESP32-S3; E-Paper 7.5in)
Access-Token: sk_live_7f8a9b2c3d4e5f6a1b2c3d4e
ID: 00:1A:2B:3C:4D:5E
Accept: application/json

Backend memverifikasi header Access-Token menggunakan perbandingan konstan (constant-time comparison) untuk mencegah timing attack, sekaligus memvalidasi header ID (MAC address perangkat) sebagai namespace konfigurasi.

Contoh Middleware Autentikasi (Node.js/Express)

import crypto from 'node:crypto';

export function requireDeviceAuth(req, res, next) {
  const token = req.header('Access-Token');
  const mac = req.header('ID');
  const expectedToken = process.env.DEVICE_API_KEY;

  if (!token || !mac) {
    return res.status(401).json({ error: 'unauthorized', reset_firmware: false });
  }

  const tokenBuf = Buffer.from(token);
  const expectedBuf = Buffer.from(expectedToken);

  if (tokenBuf.length !== expectedBuf.length || !crypto.timingSafeEqual(tokenBuf, expectedBuf)) {
    return res.status(403).json({ error: 'forbidden', reset_firmware: false });
  }

  req.deviceId = mac;
  next();
}

2. Desain Payload JSON Hemat Bandwidth

Mengurai format JSON besar memakan alokasi heap mikrokontroler dan berisiko memicu out-of-memory crash. Payload respons server harus datar, menggunakan nama kunci pendek, dan hanya membawa instruksi render atau URL gambar 1-bit monokrom mentah (BMP/binary buffer siap cetak ke framebuffer driver).

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "status": 200,
  "image_url": "https://cdn.example.com/rendered/001a2b3c4d5e.bin",
  "update_interval": 900,
  "refresh_rate": 900,
  "reset_firmware": false
}

Field update_interval memberi tahu mikrokontroler durasi deep sleep dalam satuan detik sebelum harus bangun kembali untuk request berikutnya. Logika server-side rendering (SSR) mengubah data teks/grafik menjadi bitmap monokrom di backend sebelum instruksi dikirim ke e-ink, sehingga perangkat keras tidak perlu melakukan parsing CSS atau font.

3. Deterministik Backoff dengan HTTP 429 dan Retry-After

Saat server backend mengalami lonjakan beban atau dependensi data hulu belum tersedia, backend harus mencegah loop retry agresif dari perangkat. Pola yang digunakan adalah mengembalikan status HTTP 429 Too Many Requests atau HTTP 503 Service Unavailable yang disertai header Retry-After.

HTTP/1.1 429 Too Many Requests
Retry-After: 300
Content-Type: application/json

{
  "error": "rate_limited",
  "retry_after": 300
}

State Machine Klien untuk Retry

Firmware perangkat wajib menerapkan aturan berikut:

  • Jika menerima respons 429, parse header Retry-After (satuan detik).
  • Gunakan nilai tersebut sebagai durasi deep sleep langsung, bukan melakukan loop polling instan.
  • Jika header Retry-After absen, gunakan deterministik exponential backoff lokal dengan full jitter: t = min(max_sleep, base_sleep * 2^attempt) + jitter.

4. Mekanisme Fallback Rendering Saat Timeout

Koneksi radio ke server dapat gagal akibat timeout transmisi seluler/Wi-Fi atau latensi backend. Jika perangkat e-ink tidak berhasil menarik payload dalam batas hard timeout (misalnya 15 detik), perangkat tidak boleh membiarkan radio aktif terus menerus.

  1. Retain Framebuffer Terakhir: Layar e-ink bersifat bistable (gambar tetap tampil tanpa daya). Jika fetch gagal, batalkan siklus refresh layar agar menghemat konsumsi energi refresh e-ink.
  2. Render Offline Indicator dari Flash Lokal: Jika backend mengembalikan payload parsial atau timeout berulang (> 3 kali), ambil icon bitmap kecil "Connection Error" dari flash storage internal perangkat, gambar di pojok kanan atas framebuffer yang ada, lalu segera trigger deep sleep darurat.
  3. Safe Sleep Default: Atur timer RTC hardware ke nilai konstan (misalnya 600 detik) jika koneksi gagal total tanpa respons status dari server.

Ringkasan Kontrak API

Kontrak API untuk e-ink menuntut backend memikul beban rendering dan penjadwalan. Penggunaan preshared key, payload deterministik yang mengontrol siklus tidur (sleep intervals), serta penanganan respons HTTP 429 menjamin konsumsi baterai perangkat tetap minimal dan beban server terkendali.