> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mertani.co.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Method

Mertani menyediakan dua metode integrasi data yang dirancang untuk kebutuhan berbeda:

|                        | **REST API**                                        | **Webhook API**                         |
| ---------------------- | --------------------------------------------------- | --------------------------------------- |
| **Pola**               | Pull-based                                          | Push-based                              |
| **Siapa yang memulai** | Client mengambil data dari Mertani                  | Mertani mengirim data ke client         |
| **Kapan digunakan**    | Saat butuh kontrol penuh atas waktu dan format data | Saat butuh data segera setelah tersedia |

Kedua metode membaca dari **sumber data yang sama** (database Mertani) dan dapat digunakan secara bersamaan, misalnya REST API untuk dashboard dan Webhook untuk sistem alerting.

***

## 1. REST API (Pull-Based)

Client secara aktif mengambil data dari server Mertani melalui HTTP `GET` request.

<Frame>
  <div>
    <img src="https://mintcdn.com/mertani/QKCSIJ_vjKyFoAyf/assets/asset-api/restapi-light.webp?fit=max&auto=format&n=QKCSIJ_vjKyFoAyf&q=85&s=4add8689f04fa5d5ed5a52e7a1f3e189" alt="Diagram alur REST API" className="dark:hidden" noZoom={true} width="1354" height="348" data-path="assets/asset-api/restapi-light.webp" />

    <img src="https://mintcdn.com/mertani/QKCSIJ_vjKyFoAyf/assets/asset-api/restapi-dark.webp?fit=max&auto=format&n=QKCSIJ_vjKyFoAyf&q=85&s=4c65b44a4ad6cd7baef137c4ecc9b135" alt="Diagram alur REST API" className="hidden dark:block" noZoom={true} width="1354" height="348" data-path="assets/asset-api/restapi-dark.webp" />
  </div>
</Frame>

### Cara Kerja

<Steps>
  <Step title="Client mengirim request">
    Client melakukan HTTP `GET` ke endpoint API Mertani, dengan parameter seperti `device_id` atau filter `timestamp`.
  </Step>

  <Step title="Backend membaca database">
    Server Mertani membaca data yang tersimpan di database. Data **tidak** diambil langsung dari device.
  </Step>

  <Step title="Response dikembalikan">
    Data dikembalikan ke client dalam format JSON.
  </Step>
</Steps>

### Ringkasan

| Aspek                  | Detail                                   |
| ---------------------- | ---------------------------------------- |
| **Metode HTTP**        | `GET`                                    |
| **Pola**               | Client mengontrol kapan data diambil     |
| **Tipe data**          | Historis, agregasi, snapshot             |
| **Real-time**          | Tidak, bergantung pada interval polling  |
| **Kompleksitas setup** | Rendah, tidak memerlukan endpoint publik |

### Use Case

* Dashboard monitoring & visualisasi
* Data analytics dan reporting
* Integrasi BI tools
* Sinkronisasi data terjadwal

***

## 2. Webhook API (Push-Based)

Mertani secara otomatis mengirim data ke endpoint client setiap kali ada data baru dari device.

<Frame>
  <div>
    <img src="https://mintcdn.com/mertani/QKCSIJ_vjKyFoAyf/assets/asset-api/webhook-light.webp?fit=max&auto=format&n=QKCSIJ_vjKyFoAyf&q=85&s=c6ad164871e589a6aa074e4b47b9cd8b" alt="Diagram alur Webhook API" className="dark:hidden" noZoom={true} width="1702" height="290" data-path="assets/asset-api/webhook-light.webp" />

    <img src="https://mintcdn.com/mertani/QKCSIJ_vjKyFoAyf/assets/asset-api/webhook-dark.webp?fit=max&auto=format&n=QKCSIJ_vjKyFoAyf&q=85&s=ba7f4673c1da9f2572be8baa2c88a6a4" alt="Diagram alur Webhook API" className="hidden dark:block" noZoom={true} width="1702" height="290" data-path="assets/asset-api/webhook-dark.webp" />
  </div>
</Frame>

### Cara Kerja

<Steps>
  <Step title="Device mengirim data">
    Device mengirim data ke backend Mertani sesuai interval yang dikonfigurasi.
  </Step>

  <Step title="Backend memproses data">
    Data divalidasi, dinormalisasi, dan disimpan ke database.
  </Step>

  <Step title="Backend mengirim ke client">
    Backend melakukan HTTP `POST` ke endpoint client yang sudah didaftarkan.
  </Step>

  <Step title="Client menerima data">
    Client memproses data secara langsung tanpa perlu melakukan request.
  </Step>
</Steps>

### Ringkasan

| Aspek                  | Detail                                               |
| ---------------------- | ---------------------------------------------------- |
| **Metode HTTP**        | `POST`                                               |
| **Pola**               | Server mengirim data saat event terjadi              |
| **Tipe data**          | Real-time, event-driven                              |
| **Real-time**          | Ya, data dikirim segera setelah tersedia             |
| **Kompleksitas setup** | Lebih tinggi, memerlukan endpoint publik yang stabil |

### Use Case

* Sistem notifikasi dan alerting
* Monitoring real-time
* Integrasi event-driven system
* Automation pipeline

***

## Perbandingan REST API vs Webhook

| **Aspek**                     | **REST API**                 | **Webhook API**                 |
| ----------------------------- | ---------------------------- | ------------------------------- |
| **Pola komunikasi**           | Pull                         | Push                            |
| **Pemicu**                    | Request dari client          | Event dari sistem               |
| **Real-time**                 | Tidak langsung               | Ya                              |
| **Beban infrastruktur**       | Di sisi client (polling)     | Di sisi server penerima         |
| **Kebutuhan endpoint publik** | Tidak                        | Ya                              |
| **Kompleksitas setup**        | Rendah                       | Menengah                        |
| **Tipe data**                 | Historis & agregasi          | Event terbaru                   |
| **Cocok untuk**               | Dashboard, report, analytics | Alerting, automation, streaming |

<Info>
  REST API dan Webhook dapat digunakan secara bersamaan. Contoh umum: gunakan REST API untuk menampilkan data historis di dashboard, dan Webhook untuk memicu notifikasi real-time saat threshold terlampaui.
</Info>

***

## Best Practice

### REST API

* Gunakan **parameter `timestamp` filter** untuk menghindari pengambilan data yang tidak diperlukan
* Sesuaikan **interval polling** dengan interval pengiriman device (hindari polling lebih sering dari data yang tersedia)
* Terapkan **caching** di sisi client untuk mengurangi beban request

### Webhook

* Pastikan endpoint memiliki **high availability**. Request yang gagal direspons dapat memicu retry dari server
* Implementasikan **idempotency** untuk menangani kemungkinan data duplikat akibat retry
* Validasi setiap incoming request menggunakan **signature atau token** untuk keamanan