Un plan de control mai calm.

Un model clar de resurse

O integrare ar trebui să funcționeze cu identificatori de server, regiuni, imagini, planuri și operațiuni explicite. Cererile de creare și reinstalare ar trebui să returneze o operațiune care poate fi verificată până la finalizare. O cerere HTTP reușită nu este același lucru cu o mașină pregătită.

Acreditări cu o sarcină limitată

Tokenurile API trebuie să poată fi revocate independent și restricționate la resursele și acțiunile minime necesare. Stochează-le într-un manager de secrete sau într-un mediu protejat. Nu trimite niciodată un token către browser doar pentru a evita scrierea unui mic backend.

Reîncercările trebuie să fie sigure

Expirările de rețea pot apărea după ce o operațiune a fost acceptată. Utilizați o cheie de idempotență pentru cererile de creare și cele sensibile la plată, inspectați starea operațiunii și respectați limitele de rată. O reîncercare ar trebui să elimine incertitudinea, nu să creeze un server facturabil suplimentar.

Verifică compatibilitatea înainte de integrare

Verificați versiunea API lansată, modelul de autentificare, formatele de eroare, paginarea, limitele de rată și domeniile de aplicare ale tokenurilor înainte de a construi o integrare. Utilizați numai pachete KoalaVPS SDK publicate din linkuri de lansare verificate.

Foaia de parcurs API

Foaia de parcurs API acoperă descoperirea catalogului, autentificarea, starea contului, facturarea crypto, ciclul de viață al serverului, cheile publice SSH și webhook-urile. Rutele de mai jos descriu contractul interfeței; accesul în producție nu este încă disponibil.

Rute de autentificare și de cont

Contractul API separă sesiunile de autentificare și cheile API. Verificați schemele de răspuns, erorile, duratele de viață ale tokenurilor și acțiunile de recuperare acceptate față de versiunea publicată pentru integrarea dumneavoastră.

• 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

Rute de catalog și facturare

Citirea catalogului nu ar trebui să necesite o plată. Crearea plății necesită un domeniu de facturare restricționat, o stare clară a facturii și o gestionare idempotentă. Confirmarea trebuie finalizată înainte de activarea serviciului.

• 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 și rute de acces

Ciclul de viață necesită confirmare explicită pentru operațiunile de anulare și reinstalare. Cheile private SSH aparțin clientului; serviciul are nevoie doar de omologii lor publici.

• 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}

Evenimente și informații publice

Webhook-urile necesită semnături verificabile, reîncercări limitate și protecție împotriva reluării. Endpoint-urile publice de încredere ar trebui să returneze dovezi reale cu dată, nu asigurări sintetice.

• 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

Autorizare și limite de trafic

Un model de domeniu de aplicare candidat este citire, servere, facturare și complet, cu maximum zece chei active per cont. Contractul API propune bugete de cereri de 120 pe minut și 3,000 pe oră pentru o cheie API, și 30 pe minut pentru traficul public. Verificați HTTP 429, Retry-After și fereastra de aplicare în documentația API lansată; aceste bugete din foaia de parcurs nu reprezintă un angajament privind capacitatea de producție.

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

SDK și versiunile de protocol

Foaia de parcurs a integrării include REST, un endpoint MCP găzduit, un pachet stdio versionat, SDK și un CLI. Verificați disponibilitatea versiunii, runtime-urile acceptate, sumele de control și compatibilitatea cu API înainte de a instala un client. Descărcările pentru producție nu sunt încă disponibile.

Resurse API, grupate după responsabilitate

Modelul API intenționat separă accesul la cont, citirea catalogului, facturarea, ciclul de viață al serverului, cheile SSH și callback-urile. Apelurile read-only nu ar trebui să creeze o comandă, iar o acreditare de facturare nu ar trebui să autorizeze automat modificările de securitate ale contului. Aceasta descrie contractul de integrare. Un endpoint de provisioning de producție și SDK lansat nu sunt disponibile prin acest site.

• Cont: sesiuni, utilizare și evenimente de audit de securitate
• Catalog: planuri, regiuni și imagini disponibile
• Servere: creare, inspectare, modificare și anulare
• Chei SSH: înregistrează materialul public și revocă cheile învechite
• Webhook-uri: înregistrează, inspectează, testează și elimină apeluri inverse semnate

O cerere către server ar trebui să rămână mică

Alegeți un identificator de plan standard, o regiune, o imagine de sistem de operare și un nume de gazdă. Limita prevăzută pentru numele de gazdă este de 64 caractere. Un serviciu activ poate genera în privat un secret de administrator sau poate accepta o cheie publică SSH înrolată. Adăugările arbitrare de disc, GPU, NIC și IP nu sunt implicite de o cerere de plan standard. Respingeți câmpurile neacceptate în loc să facturați în tăcere o actualizare presupusă.

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

Scope-urile și limitele cheilor fac parte din contract

Grupurile de privilegii propuse sunt citire, servere, facturare și administrarea completă a contului. O cheie ar trebui afișată o singură dată la creare, stocată în mod privat și revocată independent de parola utilizatorului. Limita preconizată a contului este de zece chei active. Înainte de a publica o implementare, verificați că fiecare operațiune respinge o cheie fără domeniul de aplicare necesar.

Publicați împreună limitele de rată și comportamentul de reîncercare

Limitele propuse sunt 120 cereri pe minut și 3,000 pe oră pentru o cheie API, și 30 cereri pe minut pentru cererile publice neautentificate la catalog. Acestea sunt valori de politică planificate, nu capacitate API măsurată. O implementare live necesită un răspuns 429 consistent, indicații Retry-After și backoff limitat al clientului. Cererile de creare și plată necesită, de asemenea, chei de idempotență stabile.

Webhook-urile sunt mesaje care pot sosi de mai multe ori

Un receptor de apeluri inverse ar trebui să verifice semnătura pe corpul original, să respingă marcajele de timp din afara ferestrei permise și să rețină identificatorii evenimentelor procesate. Persistați evenimentul înainte de a-l confirma, apoi aplicați modificarea în mod idempotent. Păstrați vizibile încercările de livrare și o cale de reluare manuală. Un apel invers este o observație despre o operațiune, nu permisiunea de a executa instrucțiuni nelegate conținute într-un payload.

Auditați fără a transforma jurnalele într-un depozit secret

Înregistrați identificatorul actorului, tipul operațiunii, resursa afectată, rezultatul și momentul, acolo unde este necesar pentru securitatea contului. Evitați înregistrarea implicită a parolelor, tokenurilor bearer, cheilor private sau a corpurilor complete ale cererilor de plată și aplicație. Stabiliți explicit retenția, accesul și istoricul vizibil pentru client. O urmă de audit de securitate și dreptul de a inspecta conținutul aplicației clientului sunt lucruri diferite.

Publicați artefactele doar când există

O lansare publică API ar trebui să includă un document OpenAPI versionat, instrucțiuni de autentificare, exemple de erori și un proces de depreciere. Un viitor CLI, pachet Python, client TypeScript sau server MCP necesită o versiune reală, sume de control și documentație întreținută. Un pachet de provisioning KoalaVPS sau un endpoint de gestionare în producție nu este publicat prin acest site.

Puțin mai multă claritate.