अच्छा API क्या बनाता है

API एक वादा है

API उन लोगों के बीच अनुबंध है जो सेवा बनाते हैं और उन लोगों (या प्रोग्रामों) के बीच जो उसे उपयोग करते हैं। एक बार clients उस पर निर्भर हो जाएँ, तो आप कोड खुलकर बदल सकते हैं पर वादा नहीं। अच्छा API सीखने में आसान (लोग जैसा अनुमान लगाते हैं वैसा व्यवहार करता है), एकरूप (हर जगह वही नाम, formats और errors), ग़लत उपयोग करना कठिन (सुरक्षित defaults, validation, साफ़ errors), अच्छी तरह दस्तावेज़ित और विकसित होने योग्य (मौजूदा users को तोड़े बिना उसमें जोड़ा जा सके) होता है। उपभोक्ता के दृष्टिकोण से डिज़ाइन करें: पूछें कि caller कौन-सा काम करना चाहता है, फिर resources और ऑपरेशन उसके अनुसार गढ़ें, अपनी database tables या आंतरिक classes उजागर करने की जगह।

उपभोक्ता के लिए डिज़ाइन करें

API अनुबंध वाला उत्पाद है: स्पष्ट resources, अनुमानित व्यवहार और विकसित होने की जगह।

रेस्तरां का मेनू

मेनू अनुबंध है: व्यंजन के नाम, क़ीमतें और विवरण। ग्राहकों को रसोई का ढाँचा जानने की ज़रूरत नहीं, और रसोइया तब तक नुस्ख़े बदल सकता है जब तक व्यंजन अपने विवरण से मेल खाता है।

कोड से पहले दस्तावेज़ लिखें

पहले उदाहरण requests और responses का खाका बनाने से अटपटे नाम और छूटे मामले तब दिखते हैं जब उन्हें ठीक करना सस्ता है। किसी साथी से सिर्फ़ खाके से API उपयोग करने की कोशिश कराएँ।

त्वरित जाँच: API के पीछे का कोड आप खुलकर क्यों बदल सकते हैं पर उसका व्यवहार नहीं?

• व्यवहार हमेशा random होता है
• कोड गुप्त है और बदला नहीं जा सकता
• Clients अनुबंध पर निर्भर हैं, इसलिए व्यवहार बदलने से वे टूट सकते हैं
• क्योंकि HTTP मना करता है