REST API और MCP एकीकरण

REST API का परिचय और प्रमाणीकरण

वर्तमान ExCoil REST API से जुड़ें: पहुँच, वास्तविक रूट, अनुरोध बॉडी, इकाइयाँ, प्रतिक्रियाएँ और संचालन सीमाएँ।

समीक्षा की तारीख 2026-11-02

1. पहुँच और REST/MCP का अंतर

REST पहुँच के लिए Enterprise या Manufacturer सदस्यता और active या trialing स्थिति आवश्यक है। सर्वर हर अनुरोध पर कुंजी के स्वामी की वर्तमान सदस्यता जाँचता है; पुराने प्लान की कुंजी होने से डाउनग्रेड या अयोग्य स्थिति के बाद पहुँच बनी नहीं रहती।

REST में /api/v1 और exk_ से शुरू होने वाली API कुंजियाँ उपयोग होती हैं। MCP एक अलग Streamable HTTP इंटरफ़ेस है, जिसका पता /api/mcp है और जो केवल Manufacturer के लिए है। इसमें अलग, मैन्युअल रूप से कॉन्फ़िगर किए गए Bearer टोकन लगते हैं। दोनों क्रेडेंशियल एक-दूसरे की जगह नहीं चलते। इन REST रूट में OAuth प्राधिकरण प्रवाह लागू नहीं है।

नीचे के रूट छह फिनयुक्त कॉइल गणना इंजन और रेफ्रिजरेंट सूची उपलब्ध कराते हैं। इनमें REST से प्रोजेक्ट बनाना/पढ़ना/बदलना/मिटाना, Shell & Tube, निर्माण फ़ाइलें या CAD/PDF निर्यात शामिल नहीं हैं। REST कुंजी का projects:read अनुमति नाम कोई प्रोजेक्ट एंडपॉइंट नहीं बनाता। विस्तृत निर्माण सामग्री केवल Manufacturer के लिए है; यह गाइड उसे REST में उपलब्ध नहीं बताती।

2. बेस URL और प्रमाणीकरण

जिस ExCoil वातावरण में API वास्तव में तैनात है, उसका ओरिजिन लेकर /api/v1 जोड़ें। उत्पादन डोमेन के लिए बेस URL https://excoil.net/api/v1 है। प्रीव्यू अलग वातावरण है; प्रीव्यू में कोड होने से उत्पादन डोमेन पर उसका प्रकाशन सिद्ध नहीं होता।

API Keys पृष्ठ पर कुंजी बनाएँ और उसका पूरा मान तुरंत सुरक्षित करें: वह केवल एक बार दिखता है। हर अनुरोध में Authorization: Bearer के बाद REST कुंजी भेजें; GET /health और GET /refrigerants में भी। Bearer का बड़ा B और उसके बाद स्पेस बनाए रखें। केवल ब्राउज़र लॉगिन कुकी इन रूट को प्रमाणित नहीं करती।

गणना POST में Content-Type: application/json भेजें। कुंजियाँ सर्वर के सुरक्षित स्टोरेज में रखें, ब्राउज़र बंडल, URL, प्रॉम्प्ट, कोड रिपॉज़िटरी या साझा लॉग में नहीं। कुंजी खोने या उजागर होने पर उसे निरस्त करके बदलें; डाउनग्रेड के बाद भी पुरानी कुंजियों का प्रबंधन उपलब्ध रहता है।

bash

BASE_URL='https://excoil.net/api/v1'
EXCOIL_API_KEY='exk_REPLACE_WITH_YOUR_REST_KEY'
curl --include "$BASE_URL/health" \
  -H "Authorization: Bearer $EXCOIL_API_KEY"

3. लागू किए गए रूट

तालिका के सभी पथ /api/v1 के सापेक्ष हैं। सभी में प्रमाणीकरण और पात्र सदस्यता आवश्यक है। गणना POST और /refrigerants के लिए calc:read भी चाहिए। /health में यह अतिरिक्त अनुमति जाँच नहीं है।

विधि	पथ	उद्देश्य
GET	/health	API स्थिति, संस्करण और टाइमस्टैम्प
GET	/refrigerants	उपलब्ध रेफ्रिजरेंट पहचानकर्ता
POST	/calculate/chilled-water	चिल्ड-वॉटर कॉइल
POST	/calculate/hot-water	हॉट-वॉटर कॉइल
POST	/calculate/steam-coil	स्टीम कॉइल
POST	/calculate/dry-cooler	ड्राई कूलर
POST	/calculate/dx-evaporator	DX इवैपोरेटर
POST	/calculate/dx-evaporator/balanced	बैलेंस सॉल्वर वाला DX इवैपोरेटर
POST	/calculate/dx-condenser	DX कंडेंसर
POST	/calculate/dx-condenser/balanced	बैलेंस सॉल्वर वाला DX कंडेंसर

4. सही JSON बॉडी बनाएँ

सामान्य गणना रूट सीधे इंजन का इनपुट ऑब्जेक्ट लेते हैं, data या inputs आवरण नहीं। चिल्ड-वॉटर और हॉट-वॉटर में air, water, coil, hydraulic और calib होते हैं; स्टीम में air, steam, coil, hydraulic और calib; ड्राई कूलर में अपने fluid, air, coil, hydraulic और calib फ़ील्ड होते हैं। DX में air, coil, ref और calib लगते हैं। आवश्यक फ़ील्ड इंजन के अनुसार बदलते हैं; वेब फ़ॉर्म का डिस्प्ले ऑब्जेक्ट या दूसरे मॉड्यूल की बॉडी कॉपी न करें।

DX इवैपोरेटर का balanced रूट अपवाद है: inputs और वैकल्पिक options वाला ऑब्जेक्ट भेजें। inputs में पूरा DX इवैपोरेटर इंजन इनपुट रखें। DX कंडेंसर का balanced रूट सीधे कंडेंसर इनपुट लेता है, इवैपोरेटर वाला inputs/options आवरण नहीं।

DX में ref.fluid के लिए /refrigerants से मिला सटीक पहचानकर्ता उपयोग करें। तालिका चुनते समय राउटर पुराने ref.refrigerant या शीर्ष-स्तरीय refrigerant को भी पहचानता है, लेकिन इंजन का मानक फ़ील्ड ref.fluid ही है। तालिका मिलने से ref के अन्य आवश्यक फ़ील्ड की जरूरत समाप्त नहीं होती।

REST आवरण बॉडी और रेफ्रिजरेंट की सीमित जाँच करता है, पूर्ण स्कीमा सत्यापन नहीं। यह इंटरफ़ेस इकाइयों को स्वतः नहीं बदलता और सभी अनुपस्थित फ़ील्ड नहीं भरता। भेजने से पहले आवश्यक मान, भौतिक सीमाएँ, ज्यामिति और कैलिब्रेशन अपने एकीकरण में जाँचें।

कैलकुलेटर के इनपुट और परिणाम विवरण

5. इकाइयाँ अनुबंध का हिस्सा हैं

API इंजन के फ़ील्ड नाम और इकाइयाँ उपयोग करती है; वेब ऐप की डिस्प्ले इकाइयों का इस पर प्रभाव नहीं है। JSON संख्याएँ पहले से परिवर्तित हों; संख्यात्मक फ़ील्ड में स्थानीय प्रारूप वाली स्ट्रिंग या इकाई का नाम न भेजें।

फ़ील्ड या प्रत्यय	अर्थ और इकाई
Vdot_m3_s; mdot_kg_s	आयतन प्रवाह m³/s; द्रव्यमान प्रवाह kg/s
T_in_C; Tevap_C; *_K	तापमान °C; तापांतर या सुपरहीट K
height_m; width_m; Do_m; wall_m	ज्यामिति मीटर में, मिलीमीटर में नहीं
P_Pa; _Pa; _kPa	नाम के अनुसार दबाव Pa या kPa में
RH_in; freeAreaRatio	0 से 1 का अंश, प्रतिशत नहीं
glycol_pct	वॉटर कॉइल का ग्लाइकोल प्रतिशत, 0–1 अंश नहीं
fpi	प्रति इंच फिन, प्रति मीटर नहीं
P_steam_kPa	स्टीम दबाव kPa गेज में, निरपेक्ष Pa में नहीं
Q_total_W; h_out	क्षमता W; CHW/DX इवैपोरेटर निकास एन्थैल्पी J/kg शुष्क वायु में

6. प्रतिक्रिया और इंजीनियरिंग निदान पढ़ें

सफल गणना {"success":true,"data":...} देती है, जहाँ data इंजन परिणाम ऑब्जेक्ट है। GET /refrigerants में इसी आवरण के भीतर पहचानकर्ताओं की सूची होती है। GET /health अलग है: यह सीधे status, version और timestamp देता है, success या data नहीं।

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

बैलेंस्ड एंडपॉइंट data में अपने सॉल्वर का परिणाम देते हैं। विशिष्ट परिणाम अनुबंध देखें; हर एंडपॉइंट में समान perf या flags पथ न मानें। कम ऊर्जा-संतुलन त्रुटि एक संख्यात्मक निदान है, स्वतंत्र सत्यापन, प्रमाणन या निर्माण की अनुमति नहीं।

json

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "<ISO-8601 टाइमस्टैम्प>"
}

7. अनुरोध सीमा और दोबारा प्रयास

सीमा प्रत्येक REST कुंजी और सर्वर प्रक्रिया पर लागू होती है। कुंजी का rateLimit उपयोग होता है; मान अनुपस्थित या शून्य होने पर प्रति मिनट 100 अनुरोध लागू होते हैं। 60 सेकंड की विंडो पहले स्वीकृत अनुरोध से शुरू होती है; इसे घड़ी के हर नए मिनट पर रीसेट होना न मानें।

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

X-RateLimit-Limit, X-RateLimit-Remaining और X-RateLimit-Reset पढ़ें। Reset सेकंड में Unix टाइमस्टैम्प है, मिलीसेकंड या अवधि नहीं। 429 में ये हेडर और rate_limit_exceeded आते हैं; यह मिडलवेयर Retry-After नहीं देता। रीसेट तक प्रतीक्षा करें, घड़ियों के अंतर का ध्यान रखें और सीमित पुनःप्रयास करें, लगातार लूप नहीं।

लिमिटर मेमोरी में है, प्रक्रिया फिर शुरू होने पर रीसेट होता है और कई प्रतिकृतियों में साझा वैश्विक कोटा नहीं है। यह थ्रूपुट, समवर्ती कार्य या प्रतिक्रिया समय की गारंटी नहीं। इस REST राउटर में प्रति-अनुरोध समय-सीमा या असिंक्रोनस जॉब/स्थिति पूछने का एंडपॉइंट नहीं है।

8. HTTP और गणना त्रुटियों का निदान

राउटर की विफलताएँ error और message देती हैं, success:false नहीं। HTTP स्थिति और त्रुटि कोड देखें, तथा जाँच के लिए संवेदनशील जानकारी हटाया हुआ संदेश रखें। पार्सर, प्रॉक्सी या बुनियादी ढाँचे की त्रुटि का शरीर अलग हो सकता है; JSON मानने से पहले सामग्री प्रकार जाँचें।

HTTP / error	अर्थ	कार्रवाई
400 / bad_request	सामान्य बॉडी गायब/ऑब्जेक्ट नहीं; DX रेफ्रिजरेंट गायब/अज्ञात; बैलेंस्ड इवैपोरेटर inputs गायब	बॉडी का ढाँचा और रेफ्रिजरेंट पहचानकर्ता ठीक करें
401 / unauthorized	Bearer हेडर गायब/गलत, कुंजी उपसर्ग गलत या कुंजी अज्ञात	हेडर और REST कुंजी जाँचें, MCP टोकन नहीं
403 / forbidden	निरस्त/समाप्त कुंजी, अयोग्य प्लान/स्थिति या अनुमति की कमी	कुंजी, स्वामी की सदस्यता और calc:read जाँचें
422 / calculation_error	सॉल्वर हैंडलर में अपवाद	संदेश, इनपुट, इकाइयाँ और कार्य-सीमा देखें; बिना बदलाव अनंत पुनःप्रयास न करें
429 / rate_limit_exceeded	कुंजी की वर्तमान मेमोरी विंडो समाप्त	सीमा हेडर के अनुसार देर से फिर प्रयास करें

json

{
  "error": "unauthorized",
  "message": "Invalid API key."
}

9. व्यावहारिक एकीकरण जाँच सूची

लक्षित वातावरण, पात्र सदस्यता और समर्पित REST कुंजी की पुष्टि करें। पूरी कुंजी सुरक्षित रखें और सामान्य निदान में केवल उपसर्ग उपयोग करें।
प्रमाणित /health से कनेक्शन जाँचें और DX के लिए /refrigerants लें। दोनों को अनुरोध बजट में गिनें।
सटीक रूट और इंजन इनपुट अनुबंध चुनें, इकाइयाँ स्पष्ट रूप से बदलें और आवश्यक फ़ील्ड जाँचें। मॉड्यूल विवरण के लिए कैलकुलेटर गाइड देखें।
POST में Authorization और Content-Type जोड़कर पूरा इनपुट सीरियलाइज़ करें। inputs/options आवरण केवल बैलेंस्ड DX इवैपोरेटर में उपयोग करें।
स्थिति, प्रतिक्रिया प्रारूप, सीमा हेडर और इंजीनियरिंग निदान जाँचें। भेजे गए इनपुट, लौटाया गया इंजन संस्करण और सभी चेतावनियाँ परिणाम के साथ रखें।
400/401/403/422 का कारण सुधारें, अंधाधुंध पुनःप्रयास न करें; 429 पर प्रतीक्षा करें। उजागर कुंजी निरस्त करें और चयन, खरीद या निर्माण से पहले इंजीनियरिंग समीक्षा कराएँ।