Satu token, dan semua yang dapat dilakukan panel pelanggan

JSON melalui HTTPS. Tidak perlu SDK, tidak perlu akun pengembang terpisah, dan tidak ada endpoint yang ada di panel pelanggan tetapi tidak ada di sini.

Endpoint Dapatkan token

Buat server

curl -X POST https://api.vpsoffshore.com/v1/servers \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"plan":"reef","image":"debian-13"}'

Langsung mengembalikan ID konfigurasi. Mesin merespons lewat SSH sekitar enam puluh detik kemudian, dan alamatnya sudah dirutekan sebelum kredensial dikirim.

20 endpoint

Semua, dalam lima kelompok

URL Dasar https://api.vpsoffshore.com/v1. Diberi versi pada jalur; v1 akan tetap berfungsi ketika v2 ada, dan tanggal penghentiannya akan diumumkan setahun sebelumnya.

Server

GET /servers Setiap layanan pada akun, beserta status, paket, dan alamat.

POST /servers Buat satu. Akan langsung mengembalikan build id; server dapat diakses sekitar satu menit kemudian.

GET /servers/{id} Satu layanan, termasuk penggunaan sumber daya secara langsung selama satu jam terakhir.

PATCH /servers/{id} Ubah paket. Mengubah ukuran tanpa perlu instal ulang, jika disk memungkinkan.

DELETE /servers/{id} Hapus mesinnya. Disk disimpan selama 14 hari, kemudian dihapus sebelum dialokasikan ulang.

POST /servers/{id}/actions reboot · shutdown · start · rebuild · rescue · reset-password.

Penyimpanan

GET /servers/{id}/snapshots Snapshot untuk satu layanan, terbaru lebih dulu.

POST /servers/{id}/snapshots Ambil satu. Tipis, sehingga cepat dan tidak menggandakan penggunaan disk Anda.

POST /snapshots/{id}/restore Pulihkan di tempat, atau ke layanan lain dengan paket yang sama atau lebih besar.

DELETE /snapshots/{id} Hapus snapshot.

Jaringan

GET /servers/{id}/addresses Alamat yang dirutekan ke sebuah layanan, v4 dan v6.

POST /servers/{id}/addresses Minta alamat tambahan, atau sebuah /29.

PUT /addresses/{ip}/rdns Atur reverse DNS. Berlaku dalam waktu satu menit, bukan pada refresh zona berikutnya.

GET /servers/{id}/bandwidth Penghitung transfer. Bersifat informasi — tidak ada kuota yang bisa dilampaui.

Katalog

GET /plans Setiap paket dengan spesifikasi dan harganya. Sumber yang sama yang menjadi dasar tampilan situs ini.

GET /images Image dan ISO yang tersedia, termasuk yang Anda unggah.

POST /images Unggah ISO melalui URL. Boot dengan konsol terpasang.

Tagihan

GET /invoices Faktur, baik yang telah dibayar maupun yang belum, lengkap dengan koin dan transaksi blockchain.

POST /invoices/{id}/pay Terbitkan alamat pembayaran untuk salah satu dari 8 koin yang diterima.

GET /credits Kompensasi SLA yang diterapkan, beserta insiden yang menyebabkan masing-masing.

Semua yang dapat dilakukan panel pelanggan ada di sini, dan tidak ada yang di sini yang tidak ada di panel pelanggan. Jika keduanya berbeda, itu adalah bug — beri tahu kami dari panel pelanggan dan hal itu akan diperbaiki, bukan didokumentasikan sebagai perilaku yang disengaja.

Bagaimana perilakunya

Empat keputusan yang akan Anda sadari dalam satu jam

Sebuah API dinilai dari jalur buruknya, bukan jalur baiknya. Tiga dari empat poin di bawah ini membahas apa yang terjadi ketika ada yang salah.

Satu token, dibuat di panel

Dikirim sebagai bearer token. Batasi cakupannya ke read-only atau ke satu layanan saja jika Anda mau; token bersifat independen dari kata sandi Anda, dan mencabut satu token tidak pernah membuat Anda keluar dari sesi.

JSON masuk, JSON keluar, tanpa perlu SDK

HTTPS biasa tanpa envelope khusus, tanpa fallback XML, dan tanpa ritual penandatanganan. Jika curl bisa melakukannya, Anda punya klien. Library resmi tersedia untuk Go, Python, dan TypeScript, dan tidak satu pun di antaranya wajib digunakan.

Rate limit yang tidak akan terpicu secara tidak sengaja

600 permintaan per menit untuk setiap token, 60 untuk panggilan pembuatan. Setiap respons membawa sisa kuota dalam sebuah header, dan jika terlampaui, hasilnya adalah 429 disertai jumlah detik yang harus ditunggu — bukan penolakan diam-diam.

Error yang menjelaskan apa yang harus dilakukan

Kode 4xx membawa kode yang dapat dibaca mesin, kalimat yang dapat dipahami manusia, dan kolom yang bermasalah. Kami lebih memilih mengembalikan error yang panjang daripada error singkat yang harus Anda tebak.

Dua hal yang Anda tulis sekali

Autentikasi, dan bagaimana bentuk sebuah error

Keduanya layak dibaca sebelum Anda menulis panggilan pertama, bukan setelah kegagalan pertama.

Autentikasi

curl https://api.vpsoffshore.com/v1/servers \
  -H "Authorization: Bearer $TOKEN"

Token dibuat di panel pelanggan dan dapat dibatasi cakupannya menjadi hanya-baca atau untuk satu layanan saja. Token bersifat independen dari kata sandi Anda, dan mencabut satu token tidak akan mengeluarkan Anda dari sesi mana pun.

Baca batas laju

X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41

Pada setiap respons, bukan hanya pada yang gagal. Melebihi batas akan mengembalikan 429 beserta jumlah detik untuk menunggu, tidak pernah berupa drop diam-diam dan tidak pernah berupa respons yang dipotong.

Galat akan menunjukkan kolom yang bermasalah

{"error":"plan_unknown",
 "message":"No plan named 'reff'. Did you mean 'reef'?",
 "field":"plan"}

Kode yang dapat dibaca mesin, kalimat yang dapat dipahami manusia, dan kolom yang bermasalah. Kesalahan yang panjang lebih murah daripada yang singkat dan harus ditebak.

Pantau konfigurasi

curl https://api.vpsoffshore.com/v1/servers/$ID \
  -H "Authorization: Bearer $TOKEN" | jq .state

Berubah dari building → running. Tidak ada webhook yang harus Anda daftarkan sebelum dapat membuat apa pun, dan polling sekali per detik masih dalam batas.

Tidak ada yang perlu diajukan

Token berada di panel pelanggan, dan panel pelanggan disertakan bersama server pertama

Tidak perlu akun developer, tidak ada persetujuan, tidak ada sandbox yang berperilaku berbeda dari production.

Mulai dengan satu server Indeks dokumentasi

Baca selanjutnya

Langkah berikutnya