कभी एक्सपायर न होने वाली API कुंजियों की समस्या
कई साल पहले जारी की गई कुंजी, जिसे कभी रोटेट नहीं किया गया और जो आज भी मान्य है, कोई सुविधा नहीं है। यह एक जोखिम है जिसे सालों से किसी ने वास्तव में देखा तक नहीं।
दस्तावेज़ों की गुणवत्ता सुविधाओं की संख्या से ज़्यादा मायने क्यों रखती है
चालीस एंडपॉइंट की सूची वाला मूल्य निर्धारण पेज पंद्रह वाले पेज से ज़्यादा सक्षम दिखता है। अक्सर यह एक चेतावनी का संकेत भी होता है। एंडपॉइंट बनाना उसे उपयोग योग्य बनाने के काम का एक छोटा हिस्सा है। बाक़ी काम दस्तावेज़ों का है: साफ़ पैरामीटर विवरण, असली उदाहरण अनुरोध और रिस्पॉन्स, एज केस के बारे में ईमानदार नोट्स, और यह सीधी व्याख्या कि कुछ ग़लत होने पर क्या होता है। चालीस एंडपॉइंट पर यह काम छोड़ दें, और आपको चालीस ऐसे फ़ीचर मिलते हैं जो तकनीकी रूप से मौजूद हैं पर व्यावहारिक रूप से लगभग नहीं।
हम ज़्यादा चीज़ों के ख़राब दस्तावेज़ों की बजाय कम चीज़ों के अच्छे दस्तावेज़ रखना पसंद करेंगे। किसी API का मूल्यांकन करने वाला डेवलपर शायद ही कभी पहले फ़ीचर सूची पढ़ता है। वह दस्तावेज़ पढ़ता है, एक उदाहरण अनुरोध आज़माता है, और पहले कुछ मिनटों में ही पूरी कंपनी के बारे में राय बना लेता है, इस आधार पर कि वह उदाहरण लिखे मुताबिक़ काम करता है या नहीं। अगर नहीं करता, तो मार्केटिंग पेज पर फ़ीचर की संख्या मायने रखना बंद कर देती है, क्योंकि आगे पढ़ते रहने के लिए ज़रूरी भरोसा उसी पल चला गया।
हमारे लिए अच्छे दस्तावेज़ों का मतलब कुछ ठोस बातें हैं, कोई अस्पष्ट वादा नहीं। इसका मतलब है कि ऑथेंटिकेशन को हर स्वीकृत तरीक़ा साफ़ दिखाते हुए समझाया जाए, न कि सिर्फ़ वह जो प्रोवाइडर पसंद करता है। इसका मतलब है कि रेट लिमिट असली संख्याओं में बताई जाएँ, न कि "उदार सीमाएँ लागू हैं" कहकर। इसका मतलब है कि एरर कोड इस जानकारी के साथ सूचीबद्ध हों कि हर एक असल में किस वजह से आता है, ताकि विफल अनुरोध को डीबग करने वाला डेवलपर केवल स्टेटस कोड से अंदाज़ा लगाने के बजाय दस्तावेज़ों में जवाब पा सके। इनमें से किसी के लिए ज़्यादा इंजीनियरिंग नहीं चाहिए। इसके लिए किसी को यह तय करना होता है कि इसे साफ़-साफ़ लिखना असली प्रोडक्ट से जुड़ा कोई वैकल्पिक, दिखावटी काम नहीं है।
केवल काम चलाऊ दस्तावेज़ों की एक बढ़ती जाने वाली लागत भी होती है। जो डेवलपर दस्तावेज़ों में जवाब नहीं ढूँढ पाता, वह सपोर्ट टिकट खोलता है, और अब उस एक सवाल को हल करने में फ़ीचर बनाने पर पहले से लगे इंजीनियरिंग समय के ऊपर स्टाफ़ का समय भी लगता है। इसे उसी अस्पष्ट पैराग्राफ़ से टकराने वाले पर्याप्त ग्राहकों से गुणा करें, और पतले दस्तावेज़ लिखने से हुई "बचत" जल्दी ही घाटे में बदल जाती है। साफ़ दस्तावेज़ API के ऊपर जोड़ी गई कोई अतिरिक्त अच्छाई नहीं हैं। एक अस्पष्ट पैराग्राफ़ से पैदा होने वाले सपोर्ट के बोझ को गिनें, तो ये विकल्प से सस्ते पड़ते हैं।
हमें यह भी लगता है कि दस्तावेज़ों की गुणवत्ता उन गिने-चुने संकेतों में से एक है जिन्हें संभावित ग्राहक किसी इंटीग्रेशन के लिए प्रतिबद्ध होने से पहले वास्तव में परख सकता है। आप पाँच मिनट में किसी प्रोवाइडर के अपटाइम इतिहास को आसानी से टेस्ट नहीं कर सकते, और पहले इंटीग्रेट किए बिना डेटा की सटीकता को पूरी तरह नहीं आँक सकते। लेकिन पाँच मिनट में आप दस्तावेज़ पढ़कर यह ज़रूर आँक सकते हैं कि उन्हें लिखने वाली कंपनी प्रोडक्ट को इतनी अच्छी तरह समझती थी कि उसे सीधे शब्दों में समझा सके, या दस्तावेज़ किसी सेल्स पेज के लिए बनी फ़ीचर सूची पर बाद में जोड़ दी गई चीज़ जैसे लगते हैं।
लंबी फ़ीचर सूची लिखना आसान है। ऐसे दस्तावेज़ जिनके आधार पर डेवलपर पहली ही कोशिश में वास्तव में कुछ बना सके, आसान नहीं हैं, और यही अंतर ठीक वह वजह है जिससे वे ज़्यादा मायने रखते हैं।