API का पता और एनवायरनमेंट

Sursa API का अपना पता है, जो उस पते से अलग है, जिससे लोग ब्राउज़र में Sursa खोलते हैं। सभी पाथ /v1 से शुरू होते हैं।

Sursa कहाँ चलता है	API का पता	यह पोर्टल
Sursa क्लाउड	`https://api.sursa.com`	`https://developers.sursa.com`
आपका अपना इंस्टॉलेशन	`https://api.<your domain>`, जैसा आपके एडमिन ने सेट किया है	API के पते पर `/developers/`
API के अलग पते के बिना आपका इंस्टॉलेशन	इंस्टॉलेशन का मुख्य पता	मुख्य पते पर `/developers/`

API का पता सिर्फ़ API के लिए है: उस पर न साइन-इन पेज है, न कुकी और न वेब इंटरफ़ेस। हर रिक्वेस्ट का ऑथेंटिकेशन API कुंजी या OAuth ऐक्सेस टोकन से होता है। इस पते के पीछे लोड बैलेंसर के साथ कई सर्वर हो सकते हैं; आपके इंटीग्रेशन को यह जानने की ज़रूरत नहीं कि वे कितने हैं।

जो इंटीग्रेशन मुख्य पते पर API कॉल करते हैं (उदाहरण के लिए, https://app.sursa.com/v1), वे काम करते रहते हैं। कुछ अंतरों और स्टेप-बाय-स्टेप बदलाव के लिए API के अलग पते पर जाना देखें।

बेस URL

हर रिक्वेस्ट अपने कॉन्फ़िगरेशन में दिए एक बेस URL से बनाएँ, ताकि वही कोड किसी भी एनवायरनमेंट पर चल सके:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

सिर्फ़ HTTPS इस्तेमाल करें, और अपनी भेजी रिक्वेस्ट के लॉग में कुंजी न आने दें।

वर्शन और स्पेसिफ़िकेशन

GET /v1/health बताता है कि पता चालू है या नहीं, और उस Sursa का वर्शन लौटाता है, जो इस पते को सर्व करता है। यह कुंजी के बिना जवाब देता है, इसलिए आप इसे मॉनिटरिंग में इस्तेमाल कर सकते हैं:

curl https://api.sursa.com/v1/health

{"ok": true, "version": "v1.4.0"}

यह Sursa रिलीज़ का वर्शन है, API का नहीं। API का वर्शन उसके स्पेसिफ़िकेशन का info.version है। API का OpenAPI 3.1 स्पेसिफ़िकेशन इसी पते पर, बिना ऑथेंटिकेशन के, प्रकाशित है:

पाथ	क्या है
`GET /openapi.json`	पब्लिक स्पेसिफ़िकेशन, जिसमें `servers` में यही पता है।
`GET /v1/openapi-public.json`	वही स्पेसिफ़िकेशन। `ETag` और `If-None-Match` सपोर्ट करता है।

इससे क्लाइंट जनरेट करें, API को Postman जैसे टूल में इम्पोर्ट करें, या CI में जाँचें कि आपका इंटीग्रेशन सिर्फ़ उसी वर्शन के ऑपरेशन इस्तेमाल करता है, जिसकी आप उम्मीद करते हैं। इस पोर्टल का API रेफ़रेंस भी इसी फ़ाइल से बनता है।

टेस्टिंग

Sursa में अलग टेस्ट मोड नहीं है: कुंजी वाली हर रिक्वेस्ट उसके संगठन के असली डेटा पर काम करती है। सुरक्षित तरीक़े से डेवलप और टेस्ट करने के लिए:

डेवलपमेंट के लिए अलग कुंजी बनाएँ, उतने ही सीमित रोल और स्कोप के साथ, जितने काम के लिए ज़रूरी हैं।
एक अलग कलेक्शन में लिखें, उदाहरण के लिए sandbox, जो सिर्फ़ आपकी टीम को दिखे, और काम पूरा होने पर उसे हटा दें।
अगर आपकी कंपनी में टेस्टिंग के लिए अलग Sursa संगठन या इंस्टॉलेशन है, तो बेस URL और कुंजी उसी की रखें। आपके कोड में और कुछ नहीं बदलता।
रीट्राई को शुरू से ही सुरक्षित बनाएँ: हर POST और PATCH के साथ Idempotency-Key भेजें।

API रेफ़रेंस के हर एंडपॉइंट पेज पर आज़माएँ कंसोल उस कुंजी के साथ असली रिक्वेस्ट भेजता है, जो आप उसमें पेस्ट करते हैं। कुंजी ब्राउज़र टैब की मेमोरी में रहती है और सिर्फ़ API के पते पर भेजी जाती है।

नेटवर्क की ज़रूरतें

आपके सर्वर से API के पते तक आउटगोइंग HTTPS (पोर्ट 443)।
जहाँ आपका नेटवर्क इसकी अनुमति देता है, वहाँ फ़ायरवॉल के नियमों में तय IP पतों के बजाय होस्ट का नाम अनुमत करें: क्षमता बढ़ने पर पते के पीछे के सर्वर बदल सकते हैं।
ब्राउज़र ऐप्लिकेशन API को सीधे कॉल कर सकते हैं: रिस्पॉन्स किसी भी ओरिजिन को अनुमति देते हैं (Access-Control-Allow-Origin: *), कुकी के बिना। ध्यान रखें कि ब्राउज़र में इस्तेमाल हुई कुंजी उस ब्राउज़र के यूज़र को दिखती है।