Isang mas kalmadong control plane.

Malinaw na modelo ng resource

Dapat gumana ang isang integration gamit ang malinaw na server identifiers, regions, images, plans at operations. Ang creation at reinstall requests ay dapat magbalik ng operation na masusuri hanggang matapos. Ang matagumpay na HTTP request ay hindi kapareho ng pagiging handa ng isang machine.

Mga credential na may limitadong trabaho

Ang mga API token ay dapat na malayang ma-revoke at limitado sa pinakamababang resource at aksyon na kailangan. Itago ang mga ito sa secret manager o protektadong environment. Huwag kailanman ipadala ang token sa browser para lamang maiwasang magsulat ng maliit na backend.

Dapat ligtas ang mga retry

Maaaring mangyari ang network timeout pagkatapos tanggapin ang isang operation. Gumamit ng idempotency key para sa creation at payment-sensitive na request, suriin ang operation state at igalang ang rate limits. Ang retry ay dapat maglinaw ng kawalan ng katiyakan, hindi gumawa ng karagdagang billable server.

Suriin ang compatibility bago ang integration

Suriin ang inilabas na bersyon ng API, modelo ng authentication, mga format ng error, pagination, rate limits at token scopes bago bumuo ng integration. Gumamit lamang ng mga nai-publish na KoalaVPS SDK package mula sa mga verified na release link.

Roadmap ng API

Saklaw ng API roadmap ang pagtuklas ng katalogo, pagpapatotoo, estado ng account, crypto billing, lifecycle ng server, pampublikong SSH key at webhooks. Inilalarawan ng mga ruta sa ibaba ang kontrata ng interface; hindi pa available ang production access.

Authentication at account route

Hinihiwalay ng kontrata ng API ang mga login session at API key. Suriin ang mga response schema, error, tagal ng token at mga sinusuportahang aksyon sa recovery laban sa bersyong inilabas para sa iyong integration.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Mga ruta ng catalogue at billing

Ang pagbabasa ng katalogo ay hindi dapat mangailangan ng bayad. Ang paggawa ng bayad ay nangangailangan ng limitadong saklaw ng pagsingil, malinaw na estado ng invoice at idempotent na paghawak. Dapat makumpleto ang kumpirmasyon bago ang pag-activate ng serbisyo.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Server at mga ruta ng access

Ang lifecycle ay nangangailangan ng malinaw na kumpirmasyon para sa mga operasyon ng pagkansela at muling pag-install. Ang mga pribadong SSH key ay nabibilang sa client; kailangan lamang ng serbisyo ang kanilang mga pampublikong katapat.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Mga kaganapan at pampublikong impormasyon

Ang mga webhook ay nangangailangan ng verifiable signatures, bounded retries at replay protection. Ang mga pampublikong trust endpoint ay dapat magbalik ng tunay na may petsang ebidensya kaysa sa sintetikong mga assurance.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Awtorisasyon at mga limitasyon sa trapiko

Ang isang kandidatong modelo ng scope ay read, servers, billing at full, na may maximum na sampung aktibong key bawat account. Iminumungkahi ng kontratang API ang mga badyet ng kahilingan na 120 kada minuto at 3,000 kada oras para sa isang API key, at 30 kada minuto para sa pampublikong trapiko. Suriin ang HTTP 429, Retry-After at ang window ng pagpapatupad sa inilabas na dokumentasyon ng API; ang mga badyet sa roadmap na ito ay hindi pangako ng kapasidad sa produksyon.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK at mga protocol release

Kasama sa integration roadmap ang REST, isang hosted na MCP endpoint, isang versioned na stdio package, SDKs at isang CLI. Suriin ang availability ng release, mga sinusuportahang runtime, checksums at compatibility ng API bago mag-install ng client. Hindi pa available ang mga production download.

Mga API resource, pinangkat ayon sa responsibilidad

Hinihiwalay ng inilaan na API ang access sa account, pagbasa ng catalogue, billing, server lifecycle, SSH key at callback. Hindi dapat gumawa ng order ang read-only na tawag, at hindi dapat awtomatikong magbigay ng pahintulot ang billing credential sa mga pagbabago sa account security. Inilalarawan nito ang integration contract. Ang production provisioning endpoint at inilabas na SDK ay hindi available sa site na ito.

• Account: mga session, paggamit at mga kaganapan sa security audit
• Catalogue: mga plan, rehiyon at available na image
• Mga server: gumawa, siyasatin, baguhin at kanselahin
• Mga SSH key: irehistro ang pampublikong materyal at bawiin ang mga lipas na key
• Webhook: irehistro, siyasatin, subukan at alisin ang mga signed callback

Dapat manatiling maliit ang isang kahilingan sa server

Pumili ng standard na identifier ng plano, rehiyon, OS image at hostname. Ang inilaan na limitasyon ng hostname ay 64 character. Ang live na serbisyo ay maaaring pribadong bumuo ng administrator secret o tumanggap ng naka-enroll na SSH public key. Ang arbitrary na pagdaragdag ng disk, GPU, NIC at IP ay hindi ipinahihiwatig ng isang standard na kahilingan sa plano. Tanggihan ang mga hindi sinusuportahang field sa halip na tahimik na maningil para sa hinulaang upgrade.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Bahagi ng kontrata ang mga scope at key limit

Ang mga iminungkahing privilege group ay read, servers, billing at full account administration. Ang isang key ay dapat ipakita nang isang beses kapag ginawa, itago nang pribado at i-revoke nang hiwalay sa password ng user. Ang nilalayong account limit ay sampung aktibong key. Bago maglathala ng implementation, i-verify na tinatanggihan ng bawat operasyon ang isang key na walang kinakailangang scope.

Ilathala nang sabay ang rate limits at retry behavior

Ang mga iminungkahing limitasyon ay 120 kahilingan kada minuto at 3,000 kada oras para sa isang API key, at 30 kahilingan kada minuto para sa mga hindi awtentikadong pampublikong kahilingan sa katalogo. Ito ay mga planadong halaga ng patakaran, hindi sinukat na kapasidad ng API. Ang isang live na implementasyon ay nangangailangan ng pare-parehong 429 na tugon, gabay sa Retry-After at may hangganang backoff ng kliyente. Ang mga kahilingan sa paggawa at pagbabayad ay nangangailangan din ng matatag na idempotency key.

Ang mga webhook ay mga mensaheng maaaring dumating nang higit sa isang beses

Dapat i-verify ng callback receiver ang signature sa orihinal na body, tanggihan ang mga timestamp sa labas ng pinapayagang window at tandaan ang mga naprosesong event identifier. I-persist ang event bago ito i-acknowledge, pagkatapos ay ilapat ang pagbabago nang idempotent. Panatilihing nakikita ang mga delivery attempt at isang manual replay path. Ang callback ay isang obserbasyon tungkol sa isang operasyon, hindi pahintulot na magsagawa ng walang kaugnayang tagubilin na nasa payload.

Mag-audit nang hindi ginagawang lihim na imbakan ang mga log

Itala ang identifier ng actor, uri ng operasyon, apektadong resource, resulta at oras kung kailangan para sa seguridad ng account. Iwasang itala ang mga password, bearer token, private key o buong katawan ng payment at application request bilang default. Gawing hayag ang retention, access at kasaysayang nakikita ng customer. Magkaiba ang security audit trail at ang pag-aangkin na siyasatin ang nilalaman ng application ng customer.

Ilabas lamang ang mga artifact kapag umiiral na ang mga ito

Ang pampublikong paglulunsad ng API ay dapat may kasamang bersyonadong dokumentong OpenAPI, mga tagubilin sa awtentikasyon, mga halimbawa ng error at proseso ng deprecation. Ang hinaharap na CLI, Python package, TypeScript client o MCP server ay nangangailangan ng aktwal na release, checksum at pinapanatiling dokumentasyon. Ang KoalaVPS provisioning package o production management endpoint ay hindi inilalabas sa pamamagitan ng site na ito.

Kaunting dagdag na kalinawan.