API के अलग पते पर जाना

पुराने इंटीग्रेशन Sursa के मुख्य पते पर API कॉल करते हैं, उसी पते पर जिसे लोग ब्राउज़र में खोलते हैं, उदाहरण के लिए https://app.sursa.com/v1/…। अब API का अपना पता भी है: क्लाउड में https://api.sursa.com या आपके इंस्टॉलेशन में https://api.<your domain>। यह इंटीग्रेशन के लिए बना है: यह लोड बैलेंसर के पीछे बढ़ाया जा सकता है, और इस पर API के अलावा कुछ नहीं चलता।

आपको जाना ज़रूरी नहीं है। मुख्य पता मौजूदा इंटीग्रेशन के लिए /v1 चलाता रहता है, बिना किसी आख़िरी तारीख़ और बिना रीडायरेक्ट के। जब आपके लिए सुविधाजनक हो, तब जाएँ, ताकि API के पते के फ़ायदे मिलें, और हर नए इंटीग्रेशन के लिए इसी पते का इस्तेमाल करें।

क्या वैसा ही रहता है

• पाथ, पैरामीटर, फ़ील्ड, एरर कोड और इवेंट: GET /v1/cards दोनों पतों पर एक ही रिक्वेस्ट है।
• API कुंजियाँ। वही kb_ और kbsrc_ कुंजियाँ दोनों पतों पर काम करती हैं, उसी रोल, स्कोप और डेटा प्रोफ़ाइल के साथ।
• आइडेम्पोटेंसी कुंजियाँ, रेट लिमिट और कोटा। दोनों पतों की रिक्वेस्ट संगठन के उन्हीं कोटा में गिनी जाती हैं।
• वेबहुक। डिलीवरी, सिग्नेचर और सीक्रेट इस पर निर्भर नहीं करते कि आप किस पते पर कॉल करते हैं।
• रिस्पॉन्स में लिंक। एरर का doc_url इस पोर्टल की ओर ले जाता है, और सूची के पेज का Link हेडर API के पते की ओर, चाहे आप किसी भी पते पर कॉल करें।

API के पते पर क्या अलग है

आख़िरी पंक्ति सिर्फ़ एक मामले में मायने रखती है: POST /v1/chat का स्ट्रीम किया गया जवाब। टूटी स्ट्रीम Last-Event-ID से सिर्फ़ उसी सर्वर पर आगे बढ़ती है, जो जवाब लिख रहा है। अगर आपका इंटीग्रेशन स्ट्रीम फिर से शुरू करता है, तो हर सवाल को request_id दें, ताकि दूसरे सर्वर पर रीट्राई को दूसरा जवाब नहीं, बल्कि सेव किया गया जवाब मिले। देखें टूटी स्ट्रीम फिर से शुरू करें।

जाने से पहले

जाँचें कि हर कॉल पब्लिक है। आपका इंटीग्रेशन जिन पाथ को कॉल करता है, उनकी सूची बनाएँ और हर एक को API रेफ़रेंस में देखें, या उनकी तुलना नए पते के स्पेसिफ़िकेशन से करें:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

जो पाथ पब्लिक रेफ़रेंस में नहीं है, वह वेब ऐप्लिकेशन का है। वह मुख्य पते पर अब भी काम करता है, पर API के पते पर नहीं चलता, और उसका ढाँचा कोई पब्लिक वादा नहीं है। उसकी जगह कोई पब्लिक एंडपॉइंट इस्तेमाल करें, या इंटीग्रेशन का वह हिस्सा मुख्य पते पर रहने दें और Sursa में अपने संपर्क व्यक्ति को बताएँ कि आपको क्या चाहिए।

जाँचें कि आप ऑथेंटिकेशन कैसे करते हैं। अगर इंटीग्रेशन यूज़र के पासवर्ड और सेशन कुकी से साइन-इन करता है, तो पहले उसे API कुंजी पर ले जाएँ। अगर वह X-API-Key भेजता है, तो Authorization: Bearer पर जाना बेहतर है, पर ज़रूरी नहीं।

अपना नेटवर्क जाँचें। अपने फ़ायरवॉल और प्रॉक्सी में नए होस्ट नाम पर आउटगोइंग HTTPS की अनुमति दें।

स्टेप-बाय-स्टेप बदलाव

1. बेस URL को अपने इंटीग्रेशन की सेटिंग बनाएँ, अगर वह पहले से सेटिंग नहीं है।

2. पढ़ने वाली रिक्वेस्ट से नया पता आज़माएँ:

   curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"
   

3. टेस्ट कुंजी और टेस्ट कलेक्शन के साथ नए पते पर अपने इंटीग्रेशन के टेस्ट चलाएँ।

4. ट्रैफ़िक का एक हिस्सा बदलें, उदाहरण के लिए एक वर्कर या एक एनवायरनमेंट, और अपने लॉग में 404 api.not_found, 401 और 5xx पर नज़र रखें। हर रिस्पॉन्स में X-Request-Id होता है; उसे अपने लॉग के साथ रखें।

5. बाक़ी ट्रैफ़िक बदलें। पुराने बेस URL को कुछ समय तक अपने कॉन्फ़िगरेशन में रखें, ताकि आप कुछ सेकंड में वापस जा सकें।

जाने के बाद क्या जाँचें

• नए पते पर GET /v1/health वही version लौटाता है, जो पुराने पते पर।
• रिस्पॉन्स में RateLimit हेडर मौजूद हैं। अगर आपका इंटीग्रेशन X-RateLimit-* के आधार पर अपनी रफ़्तार धीमी करता है, तो वह ऐसा करता रह सकता है: दोनों सेट भेजे जाते हैं। देखें रेट लिमिट और कोटा।
• अगर आपका इंटीग्रेशन ब्राउज़र में चलता है, तो उसे CORS के लिए अपने प्रॉक्सी की ज़रूरत नहीं रहती: API का पता किसी भी ओरिजिन से, कुकी के बिना, रिक्वेस्ट की अनुमति देता है।