Rauhallisempi hallintataso.

Selkeä resurssimalli

Integraation tulee toimia selkeillä palvelintunnisteilla, alueilla, levykuvilla, suunnitelmilla ja operaatioilla. Luonti- ja uudelleenasennuspyyntöjen tulee palauttaa operaatio, jonka valmistumisen voi tarkistaa. Onnistunut HTTP-pyyntö ei ole sama asia kuin valmis kone.

Tunnistetiedot rajatulla tehtävällä

API-tunnisteiden tulee olla itsenäisesti peruutettavissa ja rajoitettuja vain tarvittaviin resursseihin ja toimintoihin. Säilytä ne salaisuuksien hallinnassa tai suojatussa ympäristössä. Älä koskaan lähetä tunnistetta selaimeen vain välttääksesi pienen taustapalvelun kirjoittamisen.

Uudelleenyritysten on oltava turvallisia

Verkkoaikakatkokset voivat tapahtua sen jälkeen, kun toiminto on hyväksytty. Käytä idempotenssiavainta luontipyyntöihin ja maksuherkkiin pyyntöihin, tarkista toiminnon tila ja noudata pyyntörajoja. Uudelleenyrityksen tulisi selvittää epävarmuus, ei luoda ylimääräistä laskutettavaa palvelinta.

Tarkista yhteensopivuus ennen integrointia

Tarkista julkaistu API-versio, todennusmalli, virhemuodot, sivutus, pyyntörajat ja tokenin käyttöalueet ennen integraation rakentamista. Käytä vain julkaistuja KoalaVPS SDK -paketteja vahvistetuista julkaisulinkeistä.

API-tiekartta

API-tiekartta kattaa luettelon löytämisen, todennuksen, tilin tilan, kryptolaskutuksen, palvelimen elinkaaren, julkiset SSH-avaimet ja webhookit. Alla olevat reitit kuvaavat rajapintasopimuksen; tuotantokäyttö ei ole vielä saatavilla.

Todennus- ja tilireitit

API-sopimus erottaa kirjautumisistunnot ja API-avaimet. Tarkista vastauskaavat, virheet, tunnusten elinajat ja tuetut palautustoimet integraatiollesi julkaistua versiota vasten.

• 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

Luettelo- ja laskutusreitit

Luettelon lukeminen ei vaadi maksua. Maksun luominen edellyttää rajoitettua laskutuslaajuutta, selkeää laskun tilaa ja idempotenttia käsittelyä. Vahvistus on suoritettava loppuun ennen palvelun aktivointia.

• 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

Palvelin- ja pääsyreitit

Elinkaari vaatii nimenomaisen vahvistuksen peruutus- ja uudelleenasennustoiminnoille. Yksityiset SSH-avaimet kuuluvat asiakasohjelmaan; palvelu tarvitsee vain niiden julkiset vastineet.

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

Tapahtumat ja julkinen tieto

Webhookit vaativat todennettavat allekirjoitukset, rajatut uudelleenyritykset ja toistonsuojauksen. Julkisten luottamuspäätepisteiden tulisi palauttaa todellista päivättyä näyttöä synteettisten vakuuttelujen sijaan.

• 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

Valtuutus ja liikennearajat

Ehdotettu käyttöalueiden malli on read, servers, billing ja full, enintään kymmenen aktiivista avainta tiliä kohden. API-sopimus ehdottaa pyyntöbudjeteiksi 120 minuutissa ja 3,000 tunnissa API-avaimelle sekä 30 minuutissa julkiselle liikenteelle. Tarkista HTTP 429, Retry-After ja valvontaikkuna julkaistusta API-dokumentaatiosta; nämä tiekartan budjetit eivät ole tuotantokapasiteettia koskeva sitoumus.

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

SDK ja protokollajulkaisut

Integraatioiden tiekartta sisältää REST-rajapinnan, ylläpidetyn MCP-päätepisteen, versioidun stdio-paketin, SDK-tiedostot ja CLI-työkalun. Tarkista julkaisujen saatavuus, tuetut ajonaikaiset ympäristöt, tarkistussummat ja API-yhteensopivuus ennen asiakasohjelman asentamista. Tuotantolataukset eivät ole vielä saatavilla.

API -resurssit vastuun mukaan ryhmiteltyinä

Aiottu API erottaa tilin käytön, luettelon lukemisen, laskutuksen, palvelimen elinkaaren, SSH-avaimet ja takaisinkutsut. Vain luku -kutsut eivät saisi luoda tilausta, eikä laskutusvaltuuden pitäisi automaattisesti valtuuttaa tilin turvallisuusmuutoksia. Tämä kuvaa integraatiosopimuksen. Tuotannon käyttöönottopäätepiste ja julkaistu SDK eivät ole saatavilla tämän sivuston kautta.

• Tili: istunnot, käyttö ja turvallisuuden valvontatapahtumat
• Luettelo: suunnitelmat, alueet ja saatavilla olevat kuvat
• Palvelimet: luonti, tarkastelu, muuttaminen ja peruutus
• SSH -avaimet: rekisteröi julkinen materiaali ja peruuta vanhentuneet avaimet
• Verkkokoukut: rekisteröi, tarkastele, testaa ja poista allekirjoitetut takaisinkutsut

Palvelinpyynnön tulisi pysyä pienenä

Valitse vakiosuunnitelman tunniste, alue, käyttöjärjestelmäkuva ja isäntänimi. Isäntänimen tarkoitettu enimmäispituus on 64 merkkiä. Käynnissä oleva palvelu voi luoda ylläpitäjän salaisuuden yksityisesti tai hyväksyä liitetyn SSH julkisen avaimen. Vakiosuunnitelman pyyntö ei tarkoita mielivaltaisia levy-, GPU-, NIC- ja IP-lisäyksiä. Hylkää tukemattomat kentät sen sijaan, että veloittaisit hiljaa arvatusta päivityksestä.

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

Käyttöalueet ja avainrajoitukset ovat osa sopimusta

Ehdotetut käyttöoikeusryhmät ovat luku, palvelimet, laskutus ja täysi tilin hallinta. Avain tulee näyttää kerran luotaessa, tallentaa yksityisesti ja peruuttaa käyttäjän salasanasta riippumatta. Aiottu tilin raja on kymmenen aktiivista avainta. Ennen toteutuksen julkaisemista varmista, että jokainen toiminto hylkää avaimen, jolla ei ole vaadittua käyttöoikeutta.

Julkaise pyyntörajoitukset ja uudelleenyrityskäyttäytyminen yhdessä

Ehdotetut rajat ovat 120 pyyntöä minuutissa ja 3,000 tunnissa API avaimelle sekä 30 pyyntöä minuutissa tunnistautumattomille julkisille luettelopyynnöille. Nämä ovat suunniteltuja käytäntöarvoja, eivät mitattua API kapasiteettia. Tuotantototeutus tarvitsee johdonmukaisen 429 -vastauksen, Retry-After-ohjeistuksen ja rajatun asiakaspuolen uudelleenyrityksen. Luonti- ja maksupyynnöt tarvitsevat myös vakaat idempotenssiavaimet.

Webhookit ovat viestejä, jotka voivat saapua useammin kuin kerran

Takaisinkutsun vastaanottajan tulee vahvistaa allekirjoitus alkuperäisestä rungosta, hylätä sallitun ikkunan ulkopuoliset aikaleimat ja muistaa käsitellyt tapahtumatunnisteet. Tallenna tapahtuma ennen kuin kuittaat sen, ja sovella muutos idempotentisti. Pidä toimitustyypit ja manuaalinen uudelleentoistopolku näkyvinä. Takaisinkutsu on havainto operaatiosta, ei lupa suorittaa hyötykuorman sisältämiä asiaankuulumattomia ohjeita.

Tarkasta muuttamatta lokeista salaisuuksien säilöä

Kirjaa toimijan tunniste, toimintotyyppi, kohderesurssi, tulos ja aika, kun se on tarpeen tilin turvallisuuden vuoksi. Vältä oletuksena salasanojen, bearer-tokenien, yksityisten avainten tai täydellisten maksu- ja sovelluspyyntöjen runkojen tallentamista. Pidä säilytys, käyttöoikeudet ja asiakkaalle näkyvä historia selkeinä. Tietoturvan auditointijälki ja väite asiakassovellusten sisällön tarkastamisesta ovat eri asioita.

Julkaise artefaktit vain, kun ne ovat olemassa

Julkisen API -julkaisun tulisi sisältää versioitu OpenAPI-dokumentti, todennusohjeet, esimerkit virheistä ja poistoprosessi. Tuleva CLI, Python-paketti, TypeScript-asiakasohjelma tai MCP -palvelin tarvitsee varsinaisen julkaisun, tarkistussummat ja ylläpidetyn dokumentaation. KoalaVPS -proviointipakettia tai tuotannon hallintapäätepistettä ei julkaista tämän sivuston kautta.

Hieman lisää selkeyttä.