VPS API quick start, paggawa ng API key at unang server

Hakbang 2. Authentication at unang request

Ipinapadala ang lahat ng request sa base address na https://helpervps.com/api/v1, kasama ang header na Authorization: Bearer API_KEY. Bilang unang request, kunin ang listahan ng server mo. Kung wala pang server, ibabalik ang bakanteng listahang [].

curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Hanggang 300 request kada minuto ang puwede sa bawat account, at hanggang 10 beses kada 10 minuto ang paggawa ng server. Sapat na ang ilang segundong pagitan sa paulit ulit na pag-check ng status. JSON ang lahat ng response, at kapag may error, ibinabalik ang hugis na {"error": "code"} kasama ang status code.

Hakbang 3. Pumili ng specs, lokasyon at image

Galing sa catalog ang lahat ng value na ilalagay sa paggawa ng server. Ibinabalik nang sabay ng GET /catalog ang mga binebentang specs (plans), lokasyon (locations), image (images) at dagdag na option (addons). Kung may jq, mas madaling piliin ang kailangang bahagi lang.

curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'

• Specs code: tulad ng s1 at s2, nagpapakita ng uri at laki. Ang type ay basic (standard SSD), fast (high-performance NVMe), cpu (dedicated CPU) o mem (high memory). Ang monthly ay buwanang bayad sa US dollar.
• Location code: pangalan ng lungsod tulad ng frankfurt, singapore at seoul.
• Image code: operating system tulad ng ubuntu-24-04, debian-13 at almalinux-10, at app tulad ng app-docker at app-wordpress.
• Dagdag na option: porsyento ng awtomatikong backup, laki at bayad kada GB ng dagdag na disk, at bayad sa proteksyon sa DDoS. Null ang option na hindi binebenta.

Kung wala pa, i-install ang jq gamit ang apt install -y jq sa Ubuntu o brew install jq sa Mac. Pareho ito sa listahang pinipili sa screen, kaya mas madaling tingnan kasama ang pagkakaiba ng specs sa pricing page.

Hakbang 4. Paggawa ng server

Ipadala ang plan, lokasyon, image at pangalan bilang JSON sa POST /servers. Bayaran ang unang termino ng napili mong plan at magsisimula ang paggawa ng server.

curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

Kapag nagtagumpay, ibabalik ang server info kasama ang status code 201. Ang id ay server code na hugis S-XXXX-XXXX-XXXX, at ito ang gagamitin sa lahat ng susunod na request. Isang beses lang kasama ang root_password sa response na ito, kaya i-save agad. Makikita rin ito sa server page nang 7 araw.

• label: pangalan ng server. Gumamit ng Latin na titik, numero, tuldok at gitling hanggang 40 character, at papalitan ng gitling ang ibang character.
• backups: kapag true, naka-on ang awtomatikong backup.
• extra_disk_gb: laki ng dagdag na NVMe block disk. Ilagay ang isa sa mga sizes_gb value sa catalog (50, 100, 250, 500, 1000).
• ddos_protection: kapag true, naka-on ang proteksyon sa DDoS.

Isinasama ang bayad sa option sa buwanang bayad ng server at ipinapakita sa monthly ng response, at awtomatikong nire-renew sa parehong halaga tuwing billing date. Hanggang 10 server ang puwede sa bawat account.

Hakbang 5. Pag-check ng status at pag-login

Nagsisimula ang bagong server sa creating, nagiging running kapag handa na, at napupunan ang ipv4 address. Sinusuri ng loop sa ibaba ang status bawat 10 segundo at ipinapakita ang IP kapag running na. Palitan ang server code ng code ng server mo.

ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

Ang status ay isa sa creating, running, stopped, rebooting, installing, suspended o check. Ang suspended ay nangangahulugang na-pause ang server dahil hindi ito nire-renew sa billing date, at ang check ay nangangahulugang sinusuri namin ang resulta ng server setup. Kapag lumabas na ang IP, kumonekta gamit ang ssh root@IP. Ang paraan ng pagkonekta ay nasa gabay sa unang login.

Hakbang 6. Power, renewal at pagbura

curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"

• start: ino-on ang huminto (stopped) na server.
• stop, reboot: ino-off o nire-restart ang tumatakbong (running) server.
• renew: nagbabayad ngayon ng 1, 3, 6 o 12 buwan. Ang isang suspended na server ay babalik din sa request na ito.
• DELETE: binubura ang server at disk at ibinabalik ang {"state": "deleted"}. Hindi nire-refund ang natitirang panahon ng nabayarang buwan.

Kapag nagpadala ng aksyong hindi magagawa sa kasalukuyang status, ibabalik ang 409 wrong_state. Halimbawa, kapag nagpadala ng start sa server na naka-on na. Ginagawa sa server page ang reinstall at paggawa ng bagong root password. Nasa gabay sa reinstall ang pagkakasunod.

Pagpapatakbo ng parehong pagkakasunod gamit ang Python

Ganito ang parehong daloy kapag isinulat bilang Python script. Gumagamit ito ng requests library (pip install requests).

import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Mga madalas makitang error code

• 401 unauthorized: wala o mali ang key. Tiyaking hugis Authorization: Bearer hvp_... ang header.
• 403 not_allowed: bubukas kapag nakumpirma na ang iyong unang bayad.
• 400 bad_request: mali ang pangalan o value ng field. Gamitin ang code ayon mismo sa catalog value.
• 402 not_enough_balance: ang halaga ng bayad ay mas mababa sa $25. Magpadala ulit ng hindi bababa sa $25.
• 409 limit: naabot na ang bilang ng server na puwedeng gawin sa account.
• 409 not_created: hindi nagawa ang server, at ang bayad ay ibabalik sa credit ng iyong account.
• 202 checking: sinusuri namin ang resulta ng server setup. Huwag magpadala ulit ng parehong request; tingnan ang iyong listahan ng server. Tatapusin ang server o ibabalik ang bayad sa credit ng iyong account.
• 404 not_found: server code o address na wala sa account mo.
• 409 wrong_state: aksyong hindi magagawa sa kasalukuyang status.
• 429 rate_limited: naabot ang limitasyon ng request kada minuto. Maghintay sandali at ipadala ulit.

Nasa API docs ang lahat ng endpoint, response field at halimbawa. Makikita sa page na VPS API ang magagawa gamit ang API at ang mga gamit nito.