P
PUGUH
EN Get Started

Praktik Terbaik

Rekomendasi untuk menggunakan ARSAKA PUGUH secara efektif.

Integrasi SDK

Gunakan Environment Variable

Jangan pernah hardcode kredensial di aplikasi Anda:

typescript 
// Bad: Hardcoded credentials
const client = new PuguhClient({
  baseUrl: 'https://api-puguh.arsaka.io',
});
await client.auth.login({ email: 'admin@company.com', password: 'secret123' });

// Good: Use environment variables
const client = new PuguhClient({
  baseUrl: process.env.PUGUH_API_URL,
});
await client.auth.login({
  email: process.env.PUGUH_EMAIL,
  password: process.env.PUGUH_PASSWORD,
});

Tangani Token Refresh

Implementasikan token refresh otomatis untuk menghindari kedaluwarsa sesi:

typescript 
// The SDK handles refresh automatically, but check for errors
try {
  const orgs = await client.organizations.list();
} catch (error) {
  if (error.statusCode === 401) {
    await client.auth.refresh();
    // Retry the request
  }
}

Gunakan Environment Application

  1. Buat application terpisah untuk development, staging, production
  2. Gunakan API key berbeda per environment
  3. Uji webhook di environment development terlebih dahulu
  4. Verifikasi di staging sebelum production

Organization

Gunakan Struktur Application

plaintext 
Organization: Acme Corp
  Application: production
    Webhooks (strict URLs only)
    Storage (encrypted)
  Application: staging
    Webhooks (test endpoints)
    Storage (relaxed limits)
  Application: development
    Webhooks (localhost OK)
    Storage (public access)

Praktik Terbaik Webhook

  • Selalu verifikasi signature webhook
  • Gunakan hanya endpoint HTTPS
  • Implementasikan idempotency di webhook handler Anda
  • Kembalikan 200 dengan cepat, proses secara asinkron
  • Pantau kegagalan pengiriman di jejak audit

Keamanan

Prinsip Least Privilege

  1. Mulai user sebagai Viewer
  2. Tingkatkan ke Member saat diperlukan
  3. Admin hanya untuk pengelolaan
  4. Owner bersifat tunggal

Audit Secara Berkala

typescript 
// Weekly audit script
const entries = await client.control.listAudit({
  startDate: sevenDaysAgo,
  actions: ['user.role_changed', 'organization.settings_updated'],
});

for (const entry of entries.items) {
  console.log(`${entry.timestamp}: ${entry.actorEmail} - ${entry.action}`);
}

Pantau Anomali

Buat alert untuk:

  • Pola akses yang tidak biasa
  • Lonjakan request yang gagal
  • Aktivitas di luar jam kerja
  • Operasi massal

Amankan API Key

typescript 
// Use environment variables
const client = new PuguhClient({
  apiKey: process.env.PUGUH_API_KEY, // Never hardcode
});

// Rotate regularly
await client.rotateApiKey(keyId);

Performa

Gunakan Pagination

Selalu paginasi result set yang besar:

typescript 
// Bad: Fetch all at once
const all = await client.control.listAudit();

// Good: Paginate
const page1 = await client.control.listAudit({ page: 1, limit: 50 });
const page2 = await client.control.listAudit({ page: 2, limit: 50 });

Tangani Rate Limit

typescript 
// Implement retry with backoff
async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429 && i < maxRetries - 1) {
        await sleep(1000 * Math.pow(2, i));
        continue;
      }
      throw error;
    }
  }
}

Monitoring

Lacak Metrik Utama

  • Latensi respons API (P50, P95, P99)
  • Tingkat keberhasilan pengiriman webhook
  • Tingkat kegagalan autentikasi
  • Tingkat error per endpoint

Atur Alert

yaml 
alerts:
  - name: High API Latency
    condition: api.latency.p99 > 500ms
    duration: 5m
    notify: ops-team

  - name: Webhook Delivery Failures
    condition: webhook.failure_rate > 10%
    duration: 15m
    notify: dev-team

Tinjau Secara Berkala

Jadwalkan tinjauan rutin:

  • Harian: Periksa status pengiriman webhook, DLQ
  • Mingguan: Tinjau audit log, metrik penggunaan
  • Bulanan: Analisis tren, optimalkan konfigurasi
  • Kuartalan: Audit keamanan, tinjauan role

Terkait