पहली बार SaaS निर्माताओं के लिए सार्वजनिक API डिज़ाइन को व्यावहारिक बनाएं: वर्ज़निंग, पेजिनेशन, रेट लिमिट्स, डॉक्स और एक छोटा SDK चुनें जिसे आप जल्दी शिप कर सकें।
एक सार्वजनिक API सिर्फ़ आपका ऐप एक्सपोज़ किया हुआ एन्डपॉइंट नहीं है। यह आपकी टीम के बाहर के लोगों के लिए एक वादा है कि जब आप प्रोडक्ट बदलेंगे तब भी कॉन्ट्रैक्ट काम करता रहेगा।
कठिनाई v1 लिखना नहीं है। मुश्किल यह है कि आप बग फिक्स करें, फीचर जोड़ें और ग्राहकों की असली ज़रूरतें सीखें तो इसे स्थिर कैसे रखें।
शुरूआती फैसले बाद में सपोर्ट टिकट के रूप में सामने आते हैं। अगर रिस्पांस बिना चेतावनी के बदलते हैं, नामकरण असंगत है, या क्लाइंट्स यह नहीं बता पाते कि रिक्वेस्ट सफल हुई या नहीं, तो आप घर्षण पैदा करते हैं। वह घर्षण अविश्वास में बदल जाता है, और अविश्वास लोगों को आपके ऊपर बिल्ड करना बंद करा देता है।
स्पीड भी मायने रखती है। ज्यादातर पहली बार SaaS निर्माता कुछ उपयोगी जल्दी शिप करना चाहते हैं, फिर उसे सुधारते हैं। ट्रेडऑफ़ सरल है: बिना नियमों के जितनी तेज़ आप शिप करेंगे, उतना ही ज़्यादा समय आपको उन फैसलों को उलटने में लगाना होगा जब असली उपयोगकर्ता आएंगे।
v1 के लिए "काफी अच्छा" आम तौर पर थोड़े से एंडपॉइंट्स का सेट होता है जो वास्तविक यूजर एक्शंस से मेल खाते हों, नामकरण और रिस्पांस शेप में स्थिरता, एक स्पष्ट परिवर्तन रणनीति (भले ही सिर्फ़ v1 हो), अनुमानित पेजिनेशन और समझदार रेट लिमिट्स, और ऐसे डॉक्स जो दिखाएँ कि क्या भेजना है और क्या वापस मिलेगा।
एक ठोस उदाहरण: कल्पना करें किसी ग्राहक ने एक इंटीग्रेशन बनाया जो रात में इनवॉइस बनाता है। अगर आप बाद में किसी फ़ील्ड का नाम बदल दें, डेट फॉर्मैट बदल दें, या चुपके से आंशिक परिणाम वापस करना शुरू कर दें, तो उनकी नौकरी रात के 2 बजे फेल हो जाएगी। वे आपकी API को दोष देंगे, अपने कोड को नहीं।
यदि आप Koder.ai जैसे चैट-ड्रिवन टूल के साथ बनाते हैं, तो कई एंडपॉइंट्स जल्दी जनरेट करना tempting हो सकता है। यह ठीक है, पर सार्वजनिक सरफेस छोटा रखें। आप आंतरिक एंडपॉइंट्स को प्राइवेट रखकर सीख सकते हैं कि क्या लॉन्ग-टर्म कॉन्ट्रैक्ट का हिस्सा होना चाहिए।
अच्छा सार्वजनिक API डिज़ाइन ग्राहक कैसे आपके प्रोडक्ट के बारे में बात करते हैं, उससे मेल खाते हुए कुछ नाम (resources) चुनकर शुरू होता है। रिसोर्स नाम स्थिर रखें भले ही आपका आंतरिक डेटाबेस बदल जाए। जब आप फीचर जोड़ें, तो कोर रिसोर्सेज़ का नाम बदलने की बजाय फ़ील्ड जोड़ना या नए एंडपॉइंट जोड़ना पसंद करें।
कई SaaS प्रोडक्ट्स के लिए एक व्यावहारिक शुरुआती सेट है: users, organizations, projects, और events. यदि आप किसी रिसोर्स को एक वाक्य में समझा नहीं सकते, तो वह सार्वजनिक करने के लिए तैयार नहीं है।
HTTP के उपयोग को सामान्य और अनुमानित रखें:
ऑथ पहले दिन बेकार नहीं होना चाहिए। अगर आपकी API मुख्य रूप से सर्वर-टू-सर्वर है (ग्राहक अपने बैकएंड से कॉल कर रहे हैं), तो API कीज़ अक्सर काफी होती हैं। अगर ग्राहकों को व्यक्तिगत एंड-यूज़र्स के रूप में काम करना है, या आप थर्ड-पार्टी इंटीग्रेशन की उम्मीद करते हैं जहाँ उपयोगकर्ता एक्सेस देते हैं, तो OAuth बेहतर फिट होता है। निर्णय साधारण भाषा में लिखें: कॉलर कौन है, और वे किसका डेटा छूने के लिए अनुमति रखते हैं?
शुरू से उम्मीदें सेट करें। क्या सपोर्टेड है बनाम बेस्ट-एफ़ोर्ट, इस पर स्पष्ट रहें। उदाहरण के लिए: list endpoints स्थिर और बैकवर्ड-कॉम्पैटिबल हैं, पर search filters बढ़ सकते हैं और संपूर्ण नहीं होंगे। इससे सपोर्ट टिकट कम होते हैं और आपको सुधारने की स्वतंत्रता मिलती है।
अगर आप Koder.ai जैसा वाइब-कोडिंग प्लेटफ़ॉर्म इस्तेमाल कर रहे हैं, तो API को एक प्रोडक्ट कॉन्ट्रैक्ट की तरह ट्रीट करें: पहले कॉन्ट्रैक्ट छोटा रखें, फिर असली उपयोग के आधार पर बढ़ाएँ, अनुमान के आधार पर नहीं।
वर्जनिंग ज्यादातर उम्मीदों के बारे में है। क्लाइंट जानना चाहते हैं: क्या मेरी इंटीग्रेशन अगले हफ्ते टूट जाएगी? आप चीज़ों को सुधारने के लिए जगह चाहते हैं बिना डर के।
हेडर-बेस्ड वर्जनिंग साफ़ लग सकती है, लेकिन यह लॉग्स, कैश और सपोर्ट स्क्रीनशॉट्स में छिप सकती है। URL वर्जनिंग आम तौर पर सबसे सरल विकल्प है: /v1/.... जब ग्राहक आपको फेलिंग रिक्वेस्ट भेजे, आप तुरंत वर्जन देख सकते हैं। यह v1 और v2 को साथ चलाना भी आसान बनाता है।
कोई चेंज ब्रेकिंग है अगर एक सही तरह से लिखे क्लाइंट बिना अपने कोड बदले काम करना बंद कर सकता है। सामान्य उदाहरण:
customer_id से customerId)एक सुरक्षित बदलाव वह है जिसे पुराने क्लाइंट्स अनदेखा कर सकते हैं। एक नया optional फ़ील्ड जोड़ना आम तौर पर सुरक्षित होता है। उदाहरण के लिए, GET /v1/subscriptions में plan_name जोड़ने से उन क्लाइंट्स को नुकसान नहीं होगा जो सिर्फ़ status पढ़ते हैं।
एक व्यावहारिक नियम: एक ही मेजर वर्ज़न के अंदर फ़ील्ड्स को न हटाएँ या रीस्पॉज़िशन न करें। नए फ़ील्ड जोड़ें, पुराने रखें, और तभी नौकरी से हटाएँ जब आप पूरे वर्ज़न को डिप्रिकेट करने के लिए तैयार हों।
इसे सरल रखें: डिप्रिकेशन्स जल्दी घोषित करें, रिस्पॉन्स में स्पष्ट वार्निंग भेजें, और एक एंड-डेट सेट करें। पहली API के लिए 90-दिन की विंडो अक्सर व्यवहारिक है। इस दौरान v1 काम करता रहे, एक छोटा माईग्रेशन नोट प्रकाशित करें, और सुनिश्चित करें कि सपोर्ट एक वाक्य में बता सके: v1 इस तारीख तक काम करेगा; यहाँ v2 में क्या बदला है।
अगर आप Koder.ai जैसे प्लेटफ़ॉर्म पर बना रहे हैं, तो API वर्ज़न्स को स्नैपशॉट की तरह ट्रीट करें: सुधारों को नई वर्ज़न में शिप करें, पुरानी वर्ज़न को स्थिर रखें, और तब ही बंद करें जब ग्राहकों को माईग्रेट करने का समय दे दें।
पेजिनेशन वह जगह है जहाँ भरोसा जीता या खोया जाता है। अगर परिणाम रिक्वेस्ट्स के बीच उछलते-फिरते हैं, लोग आपकी API पर भरोसा करना बंद कर देते हैं।
डेटा सेट छोटा है, क्वेरी सरल है, और उपयोगकर्ता अक्सर पेज 3 जैसी पेज तक जाना चाहते हैं तो page/limit इस्तेमाल करें। जब लिस्ट बड़ी हो सकती है, नए आइटम अक्सर आते हों, या उपयोगकर्ता बहुत सॉर्ट और फ़िल्टर करते हों तो cursor-based पेजिनेशन इस्तेमाल करें। करसर पेजिनेशन नए रिकॉर्ड्स के आने पर भी सीक्वेंस को स्थिर रखता है।
कुछ नियम पेजिनेशन को भरोसेमंद रखते हैं:
Totals मुश्किल हैं। total_count बड़े टेबल्स पर महंगा हो सकता है, खासकर फिल्टर्स के साथ। अगर आप इसे सस्ते में दे सकते हैं तो शामिल करें। नहीं दे सकते तो छोड़ दें या किसी क्वेरी फ्लैग के ज़रिये optional बनाइए।
यहाँ सरल request/response शेप्स हैं।
// Page/limit
GET /v1/invoices?page=2&limit=25&sort=created_at_desc
{
"items": [{"id":"inv_1"},{"id":"inv_2"}],
"page": 2,
"limit": 25,
"total_count": 142
}
// Cursor-based
GET /v1/invoices?limit=25&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDozMDowMFoiLCJpZCI6Imludl8xMDAifQ==
{
"items": [{"id":"inv_101"},{"id":"inv_102"}],
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDoyNTowMFoiLCJpZCI6Imludl8xMjUifQ=="
}
रेट लिमिट्स सख़्ती के बारे में कम और ऑनलाइन रहने के बारे में ज़्यादा हैं। ये आपके ऐप को ट्रैफ़िक स्पाइक्स से बचाते हैं, आपके डेटाबेस को महंगे क्वेरीज से बचाते हैं और आपके बिल से अचानक आश्चर्यजनक खर्चों को रोकते हैं। एक लिमिट क्लाइंट्स को बताती है कि सामान्य उपयोग कैसा दिखता है।
सरल शुरू करें और बाद में ट्यून करें। कुछ ऐसा चुनें जो सामान्य उपयोग को कवरेज दे और छोटे बर्स्ट की जगह दे, फिर असली ट्रैफिक को देखें। अगर आपके पास कोई डेटा नहीं है, तो एक सुरक्षित डिफ़ॉल्ट प्रति-API-की लिमिट जैसे 60 request प्रति मिनट और थोड़ी बर्स्ट अलाउन्स देना ठीक है। अगर कोई एंडपॉइंट बहुत भारी है (जैसे search या exports), तो उसे कड़ा लिमिट दें या अलग कॉस्ट रूल रखें बजाय हर रिक्वेस्ट को सज़ा देने के।
जब आप लिमिट लागू करें, क्लाइंट्स के लिए सही व्यवहार आसान बनाइए। 429 Too Many Requests लौटाएँ और कुछ मानक हेडर्स शामिल करें:
X-RateLimit-Limit: विंडो में अधिकतमX-RateLimit-Remaining: कितने बचे हैंX-RateLimit-Reset: कब विंडो रीसेट होगा (टाइमस्टैम्प या सेकंड)Retry-After: रिट्राय करने से पहले कितना इंतज़ार करेंक्लाइंट्स को 429 को एक सामान्य स्थिति समझनी चाहिए, एक ऐसी त्रुटि नहीं जिसे वे लड़ें। एक शिष्ट retry पैटर्न दोनों पक्षों को खुश रखता है:
Retry-After मौजूद हो तो उसके लिए प्रतीक्षा करेंउदाहरण: अगर किसी ग्राहक का नाइटली सिंक आपकी API को भारी मार रहा है, तो उनका जॉब रिक्वेस्ट्स को एक मिनट में फैला सकता है और 429s पर अपने आप धीमा कर सकता है बजाय पूरे रन को फेल कर देने के।
अगर आपकी API की एरर्स पढ़ने में मुश्किल हैं तो सपोर्ट टिकट जल्दी बढ़ते हैं। एक एरर शेप चुनें और हर जगह उस पर बने रहें, 500s सहित। एक सरल स्टैण्डर्ड हो सकता है: code, message, details, और एक request_id जिसे यूज़र सपोर्ट चैट में पेस्ट कर सके।
यहाँ एक छोटा, अनुमानित फ़ॉर्मैट है:
{
"error": {
"code": "validation_error",
"message": "Some fields are invalid.",
"details": {
"fields": [
{"name": "email", "issue": "must be a valid email"},
{"name": "plan", "issue": "must be one of: free, pro, business"}
]
},
"request_id": "req_01HT..."
}
}
HTTP स्टेटस कोड्स का उपयोग हर बार एक ही तरीके से करें: 400 गलत इनपुट के लिए, 401 जब ऑथ गायब या अमान्य हो, 403 जब यूज़र ऑथेंटिकेटेड है पर अनुमति नहीं है, 404 जब रिसोर्स नहीं मिला, 409 कॉन्फ्लिक्ट के लिए (जैसे duplicate unique value या गलत स्टेट), 429 रेट लिमिट्स के लिए, और 500 सर्वर एरर के लिए। सुसंगतता चालाकी से ज़्यादा मायने रखती है।
वेलिडेशन एरर्स को ठीक करना आसान बनाइए। फ़ील्ड-लेवल हिंट्स को उस सटीक पैरामीटर नाम की ओर इशारा करना चाहिए जिसका आपने डॉक्स में उपयोग किया है, न कि किसी आंतरिक डेटाबेस कॉलम की तरफ़। अगर कोई फॉर्मैट ज़रूरी है (date, currency, enum), बताइए आप क्या स्वीकार करते हैं और एक उदाहरण दिखाइए।
रिट्राय्स वह जगह हैं जहाँ कई APIs अनजाने में डुप्लिकेट डेटा बना देते हैं। महत्वपूर्ण POST एक्शन्स (payments, invoice creation, sending emails) के लिए idempotency keys सपोर्ट करें ताकि क्लाइंट्स सुरक्षित तरीके से retry कर सकें।
Idempotency-Key हेडर स्वीकार करें।वह एक हेडर नेटवर्क फ्लैक या क्लाइंट टाइमआउट्स में बहुत सी पेनफुल एज केस रोक देता है।
मान लीजिए आप एक सिंपल SaaS चलाते हैं जिसके तीन मुख्य ऑब्जेक्ट्स हैं: projects, users, और invoices. एक प्रोजेक्ट में कई यूज़र्स होते हैं, और हर प्रोजेक्ट को मासिक इनवॉइस मिलते हैं। क्लाइंट्स चाहते हैं कि वे इनवॉइसेस को अपने अकाउंटिंग टूल में सिंक करें और अपने ऐप में बेसिक बिलिंग दिखाएँ।
एक साफ़ v1 कुछ इस तरह दिख सकता है:
GET /v1/projects/{project_id}
GET /v1/projects/{project_id}/invoices
POST /v1/projects/{project_id}/invoices
अब एक ब्रेकिंग चेंज होता है। v1 में आप इनवॉइस अमाउंट्स को सेंट्स में integer के रूप में स्टोर करते हैं: amount_cents: 1299. बाद में आपको मल्टी-करेंसी और दशमलव चाहिए, इसलिए आप चाहते हैं amount: "12.99" और currency: "USD". अगर आप पुराने फ़ील्ड को ओवरराइट कर दें तो हर मौजूदा इंटीग्रेशन टूट जाएगा। वर्ज़निंग पैनिक से बचाती है: v1 को स्थिर रखें, /v2/... शिप करें नए फ़ील्ड्स के साथ, और क्लाइंट्स माईग्रेट कर लें तब तक दोनों को सपोर्ट करें।
इनवॉइस लिस्टिंग के लिए, एक अनुमानित पेजिनेशन शेप उपयोग करें। उदाहरण:
GET /v1/projects/p_123/invoices?limit=50&cursor=eyJpZCI6Imludl85OTkifQ==
200 OK
{
"data": [ {"id":"inv_1001"}, {"id":"inv_1000"} ],
"next_cursor": "eyJpZCI6Imludl8xMDAwIn0="
}
एक दिन किसी ग्राहक ने लूप में इनवॉइसेस इम्पोर्ट कीं और आपकी रेट लिमिट ट्रीगर हो गई। रैंडम फेल्स की बजाय उन्हें एक स्पष्ट रिस्पॉन्स मिलता है:
429 Too Many RequestsRetry-After: 20{ "error": { "code": "rate_limited" } }उनकी तरफ़ से क्लाइंट 20 सेकंड रुकेगा, फिर उसी cursor से जारी रखेगा बिना सब कुछ फिर से डाउनलोड किए या डुप्लिकेट इनवॉइस बनाए।
एक v1 लॉन्च तब बेहतर होता है जब आप उसे छोटे प्रोडक्ट रिलीज़ की तरह ट्रीट करें, न कि एंडपॉइंट्स के ढेर की तरह। लक्ष्य सरल है: लोग उस पर बिल्ड कर सकें, और आप बिना आश्चर्यों के इसे सुधारते रहें।
सबसे पहले एक पेज लिखें जो बताता है कि आपकी API किस लिए है और क्या नहीं है। सरफेस इतना छोटा रखें कि आप इसे एक मिनट में ज़ुबानी समझा सकें।
इस क्रम का उपयोग करें और तब तक आगे न बढ़ें जब तक हर स्टेप काफी अच्छा न हो:
अगर आप कोड-जनरेटिंग वर्कफ़्लो का उपयोग कर रहे हैं (उदाहरण के लिए Koder.ai से endpoints और responses scaffold करना), तो भी नकली-क्लाइंट टेस्ट करें। जनरेटेड कोड सही दिख सकता है पर इस्तेमाल में अजीब हो सकता है।
इसका परिणाम: कम सपोर्ट ईमेल, कम हॉटफ़िक्स रिलीज़, और एक v1 जिसे आप वास्तव में मेंटेन कर सकते हैं।
पहला SDK कोई दूसरा प्रोडक्ट नहीं है। इसे अपने HTTP API के चारों ओर एक पतला, दोस्ताना रैपर समझें। इसे सामान्य कॉल्स को आसान बनाना चाहिए, पर यह API के काम करने के तरीके को छिपाए नहीं। अगर किसी को कोई फीचर चाहिए जो आपने अभी नहीं रैप किया है, तो उन्हें रॉ रिक्वेस्ट करने का रास्ता मिलना चाहिए।
एक भाषा चुनें शुरू करने के लिए, जो आपके ग्राहकों द्वारा असल में उपयोग की जाती है। कई B2B SaaS APIs के लिए यह अक्सर JavaScript/TypeScript या Python होता है। एक सॉलिड SDK तीन आधे-खत्म SDKs से बेहतर है।
एक अच्छा स्टार्टर सेट है:
आप इसे हाथ से बना सकते हैं या OpenAPI spec से जनरेट कर सकते हैं। जनरेशन तब बढ़िया है जब आपका स्पेस सटीक हो और आप consistent typing चाहते हों, पर यह अक्सर बहुत कोड पैदा करता है। शुरुआती दौर में, हाथ से लिखा एक मिनिमल क्लाइंट और डॉक्स के लिए एक OpenAPI फ़ाइल आम तौर पर काफी होता है। बाद में आप जनरेटेड क्लाइंट्स पर स्विच कर सकते हैं बशर्ते सार्वजनिक SDK इंटरफ़ेस स्थिर रहे।
आपका API वर्ज़न आपकी कम्पैटिबिलिटी नियमों का पालन करे। आपका SDK वर्ज़न पैकेजिंग नियमों का पालन करे।
अगर आप नए optional पैरामीटर्स या नए एंडपॉइंट्स जोड़ते हैं, तो यह आम तौर पर एक माइनर SDK बंप है। मेजर SDK रिलीज़ सिर्फ़ तब रखें जब SDK में ब्रेकिंग चेंज हों (रनेम्ड मेथड्स, बदले हुए डिफ़ॉल्ट्स), भले ही API वही रही हो। यह अलगाव अपग्रेड्स को शांत और सपोर्ट टिकट्स को कम रखता है।
ज़्यादातर API सपोर्ट टिकट्स बग के बारे में नहीं होते। वे आश्चर्यों के बारे में होते हैं। सार्वजनिक API डिज़ाइन ज्यादातर बेरंग और अनुमानित रहने के बारे में है ताकि क्लाइंट कोड महीनों तक काम करता रहे।
सबसे तेज़ तरीका भरोसा खोने का यह है कि रिस्पॉन्स बिना बताये बदल जाएँ। अगर आप फ़ील्ड का नाम बदलते हैं, टाइप बदलते हैं, या जहाँ पहले वैल्यू होती थी वहां null लौटाने लगते हैं, आप क्लाइंट्स को ऐसे तरीक़े से तोड़ देंगे जिन्हें डिबग करना मुश्किल है। अगर वास्तव में व्यवहार बदलना आवश्यक है, तो वर्ज़न करें, या नया फ़ील्ड जोड़ें और पुराने को कभी-कभार के लिए रखें एक स्पष्ट सनसेट प्लान के साथ।
पेजिनेशन भी बार-बार समस्या करता है। समस्याएँ तब आती हैं जब एक एंडपॉइंट page/pageSize उपयोग करता है, दूसरा offset/limit, और तीसरा cursors, सभी के अलग defaults के साथ। v1 के लिए एक पैटर्न चुनें और हर जगह उसी पर टिके रहें। सॉर्टिंग भी स्थिर रखें ताकि नई रिकॉर्ड्स आने पर next page आइटम्स skip या repeat न हों।
एरर्स भी बहुत ईमेल-थ्रेड्स बनाते हैं जब वे असंगत होते हैं। एक सामान्य विफलता मोड है जिसमें एक सर्विस { "error":"..." } लौटाती है और दूसरी { "message":"..." }, और वे समान मुद्दे के लिए अलग HTTP स्टेटस कोड्स भेजती हैं। तब क्लाइंट्स messy, endpoint-specific handlers बना लेते हैं।
यहाँ पाँच गलतियाँ जो सबसे लंबे ईमेल थ्रेड जनरेट करती हैं:
एक साधारण आदत मदद करती है: हर रिस्पॉन्स में एक request_id शामिल करें, और हर 429 में बताएं कब रिट्राय करना है।
किसी भी चीज़ को प्रकाशित करने से पहले, consistency पर फाइनल पास करें। अधिकांश सपोर्ट टिकट्स इसलिए आते हैं क्योंकि छोटे-छोटे विवरण एंडपॉइंट्स, डॉक्स, और उदाहरणों में मेल नहीं खाते।
त्वरित चेक्स जो सबसे ज़्यादा इश्यू पकड़ते हैं:
लॉन्च के बाद, देखें कि लोग असल में क्या हिट करते हैं, इसके बजाय कि आपने क्या सोचा था वे यूज़ करेंगे। एक छोटा डैशबोर्ड और साप्ताहिक समीक्षा शुरुआती दौर में काफी है।
पहले इन संकेतकों की निगरानी करें:
फीडबैक इकट्ठा करें बिना सब कुछ फिर से लिखे। डॉक्स में एक छोटा रिपोर्ट/इश्यू पाथ जोड़ें, और हर रिपोर्ट को एंडपॉइंट, request id, और क्लाइंट वर्ज़न के साथ टैग करें। जब आप कुछ ठीक करें, तो additive बदलावों को प्राथमिकता दें: नए फ़ील्ड्स, नए optional पैरामीटर्स, या नया एंडपॉइंट, बजाय मौजूदा व्यवहार को तोड़ने के।
अगले कदम: अपने रिसोर्सेज़, वर्ज़निंग प्लान, पेजिनेशन नियम और एरर फॉर्मैट वाला एक पेज-लंबाई API स्पेक लिखें। फिर डॉक्स और एक छोटा स्टार्टर SDK बनाइए जो ऑथ और 2–3 कोर एंडपॉइंट्स को कवर करे। यदि आप तेज़ी से बढ़ना चाहते हैं, तो आप Koder.ai जैसे चैट-आधारित प्लान का उपयोग करके स्पेस, डॉक्स, और स्टार्टर SDK ड्राफ्ट कर सकते हैं (उसका planning mode endpoints और उदाहरणों को मैप करने के लिए handy है)।
Start with 5–10 endpoints that map to real customer actions.
A good rule: if you can’t explain a resource in one sentence (what it is, who owns it, how it’s used), keep it private until you learn more from usage.
Pick a small set of stable nouns (resources) customers already use in conversation, and keep those names stable even if your database changes.
Common starters for SaaS are users, organizations, projects, and events—then add more only when there’s clear demand.
Use the standard meanings and be consistent:
GET = read (no side effects)POST = create or start an actionPATCH = partial updateDELETE = remove or disableThe main win is predictability: clients shouldn’t guess what a method does.
Default to URL versioning like /v1/....
It’s easier to see in logs and screenshots, easier to debug with customers, and simpler to run v1 and v2 side by side when you need a breaking change.
A change is breaking if a correct client can fail without changing their code. Common examples:
Adding a new optional field is usually safe.
Keep it simple:
A practical default is a 90-day window for a first API, so customers have time to migrate without panic.
Pick one pattern and stick to it across all list endpoints.
Always define a default sort and a tie-breaker (like created_at + ) so results don’t jump around.
Start with a clear per-key limit (for example 60 requests/minute plus a small burst), then adjust based on real traffic.
When limiting, return 429 and include:
X-RateLimit-LimitX-RateLimit-RemainingUse one error format everywhere (including 500s). A practical shape is:
code (stable identifier)message (human-readable)details (field-level issues)request_id (for support)Also keep status codes consistent (400/401/403/404/409/429/500) so clients can handle errors cleanly.
If you generate lots of endpoints quickly (for example with Koder.ai), keep the public surface small and treat it as a long-term contract.
Do this before launch:
POST actionsThen publish a tiny SDK that helps with auth, timeouts, retries for safe requests, and pagination—without hiding how the HTTP API works.
idX-RateLimit-ResetRetry-AfterThis makes retries predictable and reduces support tickets.