Sekilas tentang API LinkHarbor

Dengan REST API Anda mengendalikan LinkHarbor dari program Anda sendiri: membuat halaman dan tautan, mengedit dan memublikasikan draf, membuat tautan pendek, atau menarik statistik ke laporan Anda sendiri. Artikel ini ditujukan bagi developer dan menjelaskan aturan dasar yang berlaku untuk setiap endpoint.

#Jalur mana yang cocok?

#Base URL dan versi

Base URL

https://dock.at-harbor.com – semua endpoint produk berada di bawah /v1, misalnya https://dock.at-harbor.com/v1/pages.

Versi

Saat ini hanya ada versi v1. Nomor versi adalah bagian dari path.

Protokol

Hanya HTTPS.

OpenAPI

Deskripsi yang bisa dibaca mesin (OpenAPI 3.1) ada di https://dock.at-harbor.com/openapi.yaml. Anda bisa memuatnya ke Postman, Insomnia, atau generator kode.

#Menguji di sandbox

Untuk pengembangan dan pengujian ada sandbox tersendiri. Sandbox berperilaku seperti API sungguhan, tetapi sepenuhnya terpisah darinya: akun sendiri, data sendiri, dan tidak ada yang masuk ke workspace Anda yang sebenarnya.

API

https://drydock.at-harbor.com, dengan path yang sama seperti di atas, misalnya https://drydock.at-harbor.com/v1/pages.

Dasbor

https://sandbox-deck.linkharbor.com, misalnya untuk membuat kunci API.

Halaman

Halaman yang dipublikasikan muncul di https://<handle>.sandbox.linkharbor.com.

Akun

Akun LinkHarbor Anda yang sebenarnya tidak berfungsi di sana. Buat akun sandbox tersendiri.

Sandbox tidak mengirim email. Jika Anda mendaftar lewat API (POST /v1/auth/register), kode verifikasi langsung dikembalikan di respons, di kolom _dev_verification. Hal yang sama berlaku untuk pengaturan ulang kata sandi dan perubahan email. Kolom ini hanya ada di sandbox, jadi jangan mengandalkannya di kode Anda.

• Notifikasi push dimatikan
• Pembayaran berjalan lewat mode uji Stripe, tidak ada uang sungguhan yang berpindah
• Rate limit sekitar sepertiga dari nilai sebenarnya, dan akun baru dibatasi 5 per jam dan alamat IP
• Setiap tanggal 1 pukul 3:00 UTC sandbox dihapus seluruhnya, dan setelah itu semua akun dan data hilang
• Setiap respons membawa header X-Environment: sandbox

#Autentikasi secara singkat

1. Sebagai pemilik atau admin, buat kunci API dengan scope yang Anda perlukan di dasbor di “Callback & API” (mulai Creator Pro)
2. Tukar ID kunci dan rahasia kunci dengan access token lewat POST /v1/token
3. Kirim token di setiap permintaan dalam header Authorization: Bearer …
4. Ambil token baru setelah 15 menit

Semua detailnya ada di Kunci API dan token, izinnya di Scope.

#Permintaan dan respons

Format

Permintaan dan respons berupa JSON dalam UTF-8. Unggahan file juga memakai multipart/form-data.

Content-Type

Kirim header Content-Type: application/json di setiap permintaan yang punya body. Jenis lain ditolak dengan 400 bad_request – termasuk jenis yang otomatis disetel curl untuk -d jika header ini tidak ada.

Kolom tidak dikenal

Kolom yang tidak dikenal oleh sebuah endpoint menghasilkan 422 validation_failed. Respons menyebutkan kolom yang tidak dikenal.

JSON rusak

Menghasilkan 400 invalid_json.

Ukuran

Tergantung endpoint-nya, body paling besar 64 KB, 1 MB, atau 2 MB, dan unggahan file 10 MB. Jika lebih besar, API merespons dengan 413 request_too_large. Semua batas tercantum di Rate limit.

Daftar

Dikirim sebagai objek dengan kolom items, misalnya {"items":[…]}.

Membuat

Merespons dengan HTTP 201 dan ID baru, misalnya {"id":123}.

Tindakan tanpa nilai kembalian

Merespons dengan {"ok":true}.

Kesalahan

Selalu punya format tetap dengan kode yang bisa dibaca mesin. Lihat Format kesalahan dan kode kesalahan.

#Paginasi

Tidak ada satu skema paginasi yang seragam. Sebagian besar daftar berukuran kecil dan dikembalikan lengkap; hanya beberapa endpoint yang punya parameter:

Untuk sort pada tautan pendek ada created_desc, created_asc, redirects_desc, dan redirects_asc; q mencari di slug, judul, dan URL tujuan (hingga 100 karakter, tidak membedakan huruf besar-kecil). Untuk statistik, period menerima 24h, 7d, 30d, 90d, this_month, last_month, last_30d, dan custom; sebagai alternatif Anda mengirim from dan to. granularity bernilai hour atau day.

#Request ID dan bahasa

• Setiap respons membawa header X-Request-Id – sertakan saat Anda menghubungi dukungan
• Jika Anda sendiri mengirim header X-Request-Id, API memakainya
• Teks kesalahan di message mengikuti bahasa akun pemilik workspace, jika tidak ada, mengikuti Accept-Language; kode di error selalu tetap sama

#Memanggil dari browser?

Secara teknis, API mengizinkan panggilan dari browser (CORS). Namun rahasia kunci tidak pernah boleh ada di kode yang berjalan di sisi pengunjung – baik di situs web maupun di aplikasi. Selalu panggil API dari server Anda sendiri.

#Paket

Tidak ada kuota panggilan API per paket. Hanya rate limit per menit yang berlaku. Batas konten paket Anda – seperti halaman, tautan, atau blok per halaman – berlaku lewat API sama seperti di dasbor. Lihat Perbandingan paket.

#Panggilan pertama Anda

# Tukar kunci dengan token
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Daftar halaman (scope read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Contoh lengkap yang menambahkan tautan, mengubah desain, dan memublikasikan ada di Memperbarui halaman lewat API.