Et roligere kontrolplan.

En klar ressourcemodel

En integration bør arbejde med eksplicitte server-id'er, regioner, images, planer og operationer. Anmodninger om oprettelse og geninstallation bør returnere en operation, der kan kontrolleres til fuldførelse. En vellykket HTTP-anmodning er ikke det samme som, at en maskine er klar.

Legitimationsoplysninger med en begrænset opgave

API-tokens bør kunne tilbagekaldes uafhængigt og begrænses til de minimale ressourcer og handlinger, der er nødvendige. Opbevar dem i en hemmelighedsmanager eller et beskyttet miljø. Send aldrig et token til browseren blot for at undgå at skrive en lille backend.

Gentagelser skal være sikre

Netværkstimeouts kan forekomme, efter en operation er accepteret. Brug en idempotency-nøgle til oprettelse og betalingsfølsomme anmodninger, undersøg operationstilstanden, og respekter hastighedsgrænser. Et nyt forsøg bør afklare usikkerhed, ikke oprette en ekstra fakturerbar server.

Kontroller kompatibilitet før integration

Kontroller den udgivne API-version, godkendelsesmodel, fejlformater, paginering, hastighedsgrænser og token-omfang, før du bygger en integration. Brug kun offentliggjorte KoalaVPS SDK-pakker fra verificerede udgivelseslinks.

API-roadmap

API-roadmappet dækker katalogopdagelse, godkendelse, kontotilstand, kryptofakturering, serverlivscyklus, offentlige SSH-nøgler og webhooks. Ruterne nedenfor beskriver interfacekontrakten; produktionsadgang er endnu ikke tilgængelig.

Godkendelses- og kontoruter

API-kontrakten adskiller loginsessioner og API-nøgler. Kontroller svar-skemaer, fejl, token-levetider og understøttede gendannelseshandlinger mod den version, der er udgivet til din 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

Katalog- og faktureringsruter

Katalogopslag bør ikke kræve en betaling. Oprettelse af betaling kræver et begrænset faktureringsområde, en klar fakturastatus og idempotent håndtering. Bekræftelse skal være gennemført, før tjenesten aktiveres.

• 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- og adgangsruter

Livscyklussen kræver eksplicit bekræftelse for annullerings- og geninstallationshandlinger. Private SSH-nøgler hører til på klienten; tjenesten har kun brug for deres offentlige modstykker.

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

Begivenheder og offentlig information

Webhooks kræver verificerbare signaturer, begrænsede genforsøg og beskyttelse mod genafspilning. Offentlige tillidsendpoints bør returnere rigtige daterede beviser i stedet for syntetiske forsikringer.

• 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

Autorisation og trafikgrænser

En kandidatmodel for omfang er læsning, servere, fakturering og fuld, med maksimalt ti aktive nøgler pr. konto. API-kontrakten foreslår anmodningsbudgetter på 120 pr. minut og 3,000 pr. time for en API-nøgle samt 30 pr. minut for offentlig trafik. Kontroller HTTP 429, Retry-After og håndhævelsesvinduet i den udgivne API-dokumentation; disse roadmap-budgetter er ikke en produktionskapacitetsforpligtelse.

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

SDK og protokoludgivelser

Integrationsroadmappet omfatter REST, et hostet MCP-endpoint, en versioneret stdio-pakke, SDKs og en CLI. Kontrollér udgivelsestilgængelighed, understøttede runtimes, checksums og API-kompatibilitet, før du installerer en klient. Produktionsdownloads er endnu ikke tilgængelige.

API-ressourcer, grupperet efter ansvar

Den tilsigtede API adskiller kontoadgang, katalogslæsning, fakturering, serverlivscyklus, SSH-nøgler og callbacks. Skrivebeskyttede kald bør ikke oprette en ordre, og en faktureringslegitimationsoplysning bør ikke automatisk godkende ændringer af kontosikkerheden. Dette beskriver integrationskontrakten. Et produktionsprovisionerings-endpoint og en udgivet SDK er ikke tilgængelige via dette websted.

• Konto: sessioner, forbrug og sikkerhedsrevisionshændelser
• Katalog: planer, regioner og tilgængelige billeder
• Servere: opret, inspicér, ændr og annullér
• SSH-nøgler: registrer offentligt materiale, og tilbagekald forældede nøgler
• Webhooks: registrer, inspicér, test og fjern signerede callbacks

En serveranmodning bør forblive lille

Vælg en standardplanidentifikator, region, OS-image og værtsnavn. Den tilsigtede grænse for værtsnavn er 64 tegn. En live tjeneste kan generere en administratorhemmelighed privat eller acceptere en tilmeldt SSH offentlig nøgle. Vilkårlige tilføjelser af disk, GPU, NIC og IP er ikke underforstået ved en standardplananmodning. Afvis ikke-understøttede felter i stedet for lydløst at opkræve for en gættet opgradering.

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

Scopes og nøglebegrænsninger er en del af kontrakten

De foreslåede privilegiegrupper er læsning, servere, fakturering og fuld kontoadministration. En nøgle bør vises én gang ved oprettelsen, opbevares privat og tilbagekaldes uafhængigt af brugerens adgangskode. Den tilsigtede kontogrænse er ti aktive nøgler. Før du offentliggør en implementering, skal du verificere, at hver handling afviser en nøgle uden det krævede omfang.

Offentliggør hastighedsgrænser og genforsøgsadfærd sammen

De foreslåede grænser er 120 forespørgsler pr. minut og 3,000 pr. time for en API nøgle samt 30 forespørgsler pr. minut for uautentificerede offentlige katalogforespørgsler. Dette er planlagte politikværdier, ikke målte API kapaciteter. En live-implementering kræver et konsistent 429 svar, Retry-After-vejledning og afgrænset klient-backoff. Oprettelses- og betalingsforespørgsler kræver også stabile idempotensnøgler.

Webhooks er beskeder, der kan ankomme mere end én gang

En callback-modtager bør verificere signaturen over den oprindelige body, afvise tidsstempler uden for det tilladte vindue og huske behandlede hændelses-id'er. Gem hændelsen, før den bekræftes, og anvend derefter ændringen idempotent. Hold leveringsforsøg og en manuel replay-sti synlig. Et callback er en observation om en operation, ikke tilladelse til at udføre urelaterede instruktioner i en payload.

Revidér uden at gøre logfiler til et hemmeligt lager

Registrér aktøridentifikatoren, handlingstypen, den berørte ressource, resultatet og tidspunktet, hvor det er nødvendigt for kontosikkerheden. Undgå som standard at registrere adgangskoder, bearer-tokens, private nøgler eller fulde betalings- og applikationsanmodningstekster. Hold opbevaring, adgang og kundesynlig historik eksplicit. Et sikkerhedsrevisionsspor og et krav om at inspicere kundens applikationsindhold er to forskellige ting.

Udgiv kun artefakter, når de findes

En offentlig API lancering bør omfatte et versioneret OpenAPI-dokument, autentificeringsinstruktioner, fejleksempler og en deprecation-proces. En fremtidig CLI, Python-pakke, TypeScript-klient eller MCP server kræver en faktisk udgivelse, checksums og vedligeholdt dokumentation. En KoalaVPS provisioning-pakke eller produktionsstyrings-endpoint udgives ikke via dette websted.

Lidt mere klarhed.