एक शांत नियंत्रण तल।

एक स्पष्ट संसाधन मॉडल

इंटीग्रेशन को स्पष्ट सर्वर पहचानकर्ताओं, क्षेत्रों, इमेज, प्लान और ऑपरेशन के साथ काम करना चाहिए। निर्माण और पुनःस्थापन अनुरोधों को ऐसा ऑपरेशन लौटाना चाहिए जिसे पूर्ण होने तक जाँचा जा सके। सफल HTTP अनुरोध का अर्थ मशीन तैयार होना नहीं है।

सीमित कार्य वाले क्रेडेंशियल

API टोकन स्वतंत्र रूप से रद्द करने योग्य होने चाहिए और न्यूनतम आवश्यक संसाधनों व क्रियाओं तक सीमित होने चाहिए। उन्हें किसी सीक्रेट मैनेजर या संरक्षित वातावरण में संग्रहीत करें। केवल एक छोटा बैकएंड लिखने से बचने के लिए कभी भी टोकन ब्राउज़र को न भेजें।

पुनः प्रयास सुरक्षित होने चाहिए

ऑपरेशन स्वीकार होने के बाद नेटवर्क टाइमआउट हो सकते हैं। निर्माण और भुगतान-संवेदनशील अनुरोधों के लिए एक आइडेम्पोटेंसी कुंजी का उपयोग करें, ऑपरेशन की स्थिति जाँचें और दर सीमाओं का सम्मान करें। पुनः प्रयास को अनिश्चितता दूर करनी चाहिए, अतिरिक्त बिल योग्य सर्वर नहीं बनाना चाहिए।

एकीकरण से पहले संगतता जाँचें

इंटीग्रेशन बनाने से पहले जारी किया गया API संस्करण, प्रमाणीकरण मॉडल, त्रुटि प्रारूप, पेजिनेशन, दर सीमाएँ और टोकन स्कोप जाँचें। केवल सत्यापित रिलीज़ लिंक से प्रकाशित KoalaVPS SDK पैकेज का उपयोग करें।

API रोडमैप

API रोडमैप में कैटलॉग खोज, प्रमाणीकरण, खाता स्थिति, क्रिप्टो बिलिंग, सर्वर जीवनचक्र, सार्वजनिक SSH कुंजियाँ और वेबहुक शामिल हैं। नीचे दिए गए रूट इंटरफ़ेस अनुबंध का वर्णन करते हैं; उत्पादन पहुँच अभी उपलब्ध नहीं है।

प्रमाणीकरण और खाता मार्ग

API अनुबंध लॉगिन सत्रों और API कुंजियों को अलग करता है। अपने इंटीग्रेशन के लिए जारी संस्करण के विरुद्ध प्रतिक्रिया स्कीमा, त्रुटियाँ, टोकन जीवनकाल और समर्थित पुनर्प्राप्ति क्रियाओं की जाँच करें।

• 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

कैटलॉग और बिलिंग मार्ग

कैटलॉग पढ़ने के लिए भुगतान की आवश्यकता नहीं होनी चाहिए। भुगतान बनाने के लिए प्रतिबंधित बिलिंग स्कोप, स्पष्ट इनवॉइस स्थिति और आइडेम्पोटेंट हैंडलिंग आवश्यक है। सेवा सक्रियण से पहले पुष्टि पूरी होनी चाहिए।

• 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

सर्वर और पहुँच मार्ग

जीवनचक्र को रद्दीकरण और पुनःस्थापन कार्यों के लिए स्पष्ट पुष्टि की आवश्यकता है। निजी SSH कुंजियाँ क्लाइंट पर होनी चाहिए; सेवा को केवल उनके सार्वजनिक समकक्षों की आवश्यकता है।

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

इवेंट और सार्वजनिक जानकारी

वेबहुक के लिए सत्यापन योग्य हस्ताक्षर, सीमित पुनःप्रयास और पुनःचलन सुरक्षा आवश्यक है। सार्वजनिक विश्वास एंडपॉइंट को कृत्रिम आश्वासनों के बजाय वास्तविक तिथि-युक्त साक्ष्य लौटाने चाहिए।

• 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

प्राधिकरण और ट्रैफ़िक सीमाएं

एक प्रस्तावित स्कोप मॉडल है read, servers, billing और full, प्रति खाता अधिकतम दस सक्रिय कुंजियों के साथ। API अनुबंध API कुंजी के लिए 120 प्रति मिनट और 3,000 प्रति घंटा के अनुरोध बजट, तथा सार्वजनिक ट्रैफ़िक के लिए 30 प्रति मिनट प्रस्तावित करता है। जारी API दस्तावेज़ में HTTP 429, Retry-After और प्रवर्तन विंडो जाँचें; ये रोडमैप बजट उत्पादन क्षमता की प्रतिबद्धता नहीं हैं।

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

SDK और प्रोटोकॉल रिलीज़

एकीकरण रोडमैप में REST, एक होस्टेड MCP एंडपॉइंट, एक संस्करणित stdio पैकेज, SDK और एक CLI शामिल हैं। क्लाइंट इंस्टॉल करने से पहले रिलीज़ उपलब्धता, समर्थित रनटाइम, चेकसम और API संगतता जाँचें। प्रोडक्शन डाउनलोड अभी उपलब्ध नहीं हैं।

API संसाधन, जिम्मेदारी के अनुसार समूहीकृत

इच्छित API खाता पहुँच, कैटलॉग पठन, बिलिंग, सर्वर जीवनचक्र, SSH कुंजियाँ और कॉलबैक को अलग करता है। केवल-पठन कॉल से ऑर्डर नहीं बनना चाहिए, और बिलिंग क्रेडेंशियल को स्वतः खाता सुरक्षा परिवर्तनों को अधिकृत नहीं करना चाहिए। यह इंटीग्रेशन अनुबंध का वर्णन करता है। इस साइट के माध्यम से उत्पादन प्रोविज़निंग एंडपॉइंट और जारी किया गया SDK उपलब्ध नहीं है।

• खाता: सत्र, उपयोग और सुरक्षा ऑडिट घटनाएँ
• कैटलॉग: प्लान, क्षेत्र और उपलब्ध इमेज
• सर्वर: बनाएँ, निरीक्षण करें, बदलें और रद्द करें
• SSH कुंजियाँ: सार्वजनिक सामग्री पंजीकृत करें और अप्रचलित कुंजियाँ रद्द करें
• वेबहुक: हस्ताक्षरित कॉलबैक पंजीकृत करें, निरीक्षण करें, परीक्षण करें और हटाएँ

सर्वर अनुरोध छोटा रहना चाहिए

मानक प्लान पहचानकर्ता, क्षेत्र, OS इमेज और होस्टनाम चुनें। इच्छित होस्टनाम सीमा 64 अक्षर है। एक लाइव सेवा निजी रूप से प्रशासक गोपनीयता उत्पन्न कर सकती है या नामांकित SSH सार्वजनिक कुंजी स्वीकार कर सकती है। मानक प्लान अनुरोध से मनमाना डिस्क, GPU, NIC और IP जोड़ना निहित नहीं है। असमर्थित फ़ील्ड अस्वीकार करें, अनुमानित अपग्रेड के लिए चुपचाप शुल्क न लें।

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

स्कोप और कुंजी सीमाएँ अनुबंध का हिस्सा हैं

प्रस्तावित विशेषाधिकार समूह पढ़ना, सर्वर, बिलिंग और पूर्ण खाता प्रशासन हैं। एक कुंजी निर्माण के समय एक बार प्रदर्शित की जानी चाहिए, निजी रूप से संग्रहीत की जानी चाहिए और उपयोगकर्ता के पासवर्ड से स्वतंत्र रूप से रद्द की जानी चाहिए। इच्छित खाता सीमा दस सक्रिय कुंजियाँ है। कार्यान्वयन प्रकाशित करने से पहले, सत्यापित करें कि प्रत्येक ऑपरेशन आवश्यक स्कोप के बिना कुंजी को अस्वीकार करता है।

दर सीमाएँ और पुनः प्रयास व्यवहार साथ में प्रकाशित करें

प्रस्तावित सीमाएँ एक API कुंजी के लिए प्रति मिनट 120 अनुरोध और प्रति घंटा 3,000 हैं, तथा अनधिप्रमाणित सार्वजनिक कैटलॉग अनुरोधों के लिए प्रति मिनट 30 अनुरोध हैं। ये नियोजित नीति मान हैं, मापी गई API क्षमता नहीं। एक लाइव कार्यान्वयन के लिए सुसंगत 429 प्रतिक्रिया, Retry-After मार्गदर्शन और सीमित क्लाइंट बैकऑफ़ आवश्यक है। निर्माण और भुगतान अनुरोधों के लिए स्थिर idempotency कुंजियाँ भी आवश्यक हैं।

वेबहुक ऐसे संदेश हैं जो एक से अधिक बार आ सकते हैं

कॉलबैक रिसीवर को मूल बॉडी पर हस्ताक्षर सत्यापित करना चाहिए, अपनी अनुमत विंडो के बाहर के टाइमस्टैम्प अस्वीकार करने चाहिए और संसाधित इवेंट पहचानकर्ताओं को याद रखना चाहिए। स्वीकार करने से पहले इवेंट को स्थायी रूप से सहेजें, फिर परिवर्तन को इडेम्पोटेंट रूप से लागू करें। डिलीवरी प्रयास और मैन्युअल रीप्ले पथ दृश्यमान रखें। कॉलबैक किसी ऑपरेशन के बारे में एक अवलोकन है, पेलोड में निहित असंबंधित निर्देशों को निष्पादित करने की अनुमति नहीं।

लॉग को गुप्त भंडार बनाए बिना ऑडिट करें

खाता सुरक्षा के लिए आवश्यक होने पर अभिनेता पहचानकर्ता, ऑपरेशन प्रकार, प्रभावित संसाधन, परिणाम और समय रिकॉर्ड करें। डिफ़ॉल्ट रूप से पासवर्ड, बियरर टोकन, निजी कुंजियाँ या पूर्ण भुगतान और एप्लिकेशन अनुरोध बॉडी रिकॉर्ड करने से बचें। प्रतिधारण, पहुँच और ग्राहक-दृश्य इतिहास स्पष्ट रखें। सुरक्षा ऑडिट ट्रेल और ग्राहक एप्लिकेशन सामग्री का निरीक्षण करने का दावा अलग-अलग चीज़ें हैं।

आर्टिफ़ैक्ट केवल तब रिलीज़ करें जब वे मौजूद हों

एक सार्वजनिक API लॉन्च में संस्करणित OpenAPI दस्तावेज़, प्रमाणीकरण निर्देश, त्रुटि उदाहरण और एक डेप्रिकेशन प्रक्रिया शामिल होनी चाहिए। भविष्य के CLI, Python पैकेज, TypeScript क्लाइंट या MCP सर्वर के लिए वास्तविक रिलीज़, चेकसम और अनुरक्षित दस्तावेज़ीकरण आवश्यक है। इस साइट के माध्यम से कोई KoalaVPS प्रोविज़निंग पैकेज या उत्पादन प्रबंधन एंडपॉइंट जारी नहीं किया जाता।

थोड़ी और स्पष्टता।