Optifora API कैसे काम करता है
यह पृष्ठ API का स्वरूप बताता है: पहचान कैसे सिद्ध होती है, संस्करण कैसे आगे बढ़ते हैं, अनुरोध किन सीमाओं में रहता है, त्रुटि कैसी दिखती है, और बाहरी दुनिया से डेटा कैसे बदला जाता है।
उत्पाद विकासाधीन है और API सतह अभी पूरी की जा रही है। एंडपॉइंट के लिए एक संदर्भ दस्तावेज़ अलग से प्रकाशित होगा; इस पृष्ठ पर कोई पता और कोई नमूना कॉल नहीं है, केवल कार्यप्रणाली है।
पहचान सत्यापन
हर अनुरोध या तो किसी व्यक्ति का होता है या किसी पंजीकृत ऐप्लिकेशन का। बिना पहचान वाला अनुरोध यदि किसी सुरक्षित एंडपॉइंट तक पहुँचे तो वह अप्रमाणित लौटता है।
- Bearer टोकनएक्सेस टोकन अनुरोध के authorization हेडर में जाता है। वह हस्ताक्षरित होता है और केवल यह बताता है कि अनुरोध किसका है।
- छोटी आयुएक्सेस टोकन मिनटों में मापी गई अवधि के बाद समाप्त हो जाता है; यह अवधि परिनियोजन की एक सेटिंग है और डिफ़ॉल्ट रूप से तीस मिनट है।
- नवीनीकरण और चक्रणसत्र refresh टोकन से बढ़ाया जाता है और हर बार बढ़ाने पर नई जोड़ी जारी होती है। यदि पहले से खर्च हो चुका refresh टोकन दूसरी बार पेश किया जाए, तो उस व्यक्ति के सभी सत्र रद्द कर दिए जाते हैं।
- अनुमतियाँ टोकन में नहीं गूँथी जातींटोकन केवल पहचान रखता है; कोई व्यक्ति क्या देख सकता है यह हर अनुरोध पर डेटाबेस से पूछा जाता है। इसलिए वापस ली गई अनुमति, हाथ में मौजूद टोकन के समाप्त होने से पहले ही काम करना बंद कर देती है।
- इंटीग्रेटर कुंजीपंजीकृत ऐप्लिकेशन अपनी ही कुंजी से जुड़ता है। सादा मान केवल एक बार, बनाते समय दिखाया जाता है; संग्रहीत केवल उसका डाइजेस्ट और वह गैर-गोपनीय उपसर्ग होता है जिससे कुंजी पहचानी जा सके।
- पहुँच संगठन देता हैकोई ऐप्लिकेशन कितना भी व्यापक रूप से उपयोग हो, संगठन द्वारा दर्ज अनुमति के बिना वह एक पंक्ति भी नहीं देखता। अनुमति दिनांकित, दायरे में सीमित और वापस ली जा सकने वाली होती है।
संस्करणन
- संस्करण पथ में रहता हैएंडपॉइंट एक संस्करण उपसर्ग के पीछे प्रकाशित होते हैं; आज की सतह संस्करण एक है।
- तोड़ने वाला बदलाव नया पथ खोलता हैमौजूदा एंडपॉइंट का अनुबंध उसी जगह पर नहीं तोड़ा जाता। असंगत बदलाव नए संस्करण पथ पर प्रकाशित होता है, जबकि पुराना काम करता रहता है।
- दस्तावेज़ अपना संस्करण स्वयं बताता हैसंदर्भ उसी संस्करण संख्या को दर्शाता है जिससे वह बना है; आप कौन-सा संस्करण पढ़ रहे हैं, इसका उत्तर दस्तावेज़ स्वयं देता है।
परिवेश और सीमाएँ
संदर्भ दो परिवेश घोषित करता है: उत्पादन और स्थानीय विकास। मूल पता इंटीग्रेटर को उसकी कुंजी के साथ सौंपा जाता है; इस पृष्ठ पर प्रकाशित नहीं होता।
- चालू होना और तैयार होना अलग-अलग मापे जाते हैंएक एंडपॉइंट बताता है कि प्रक्रिया चालू है; दूसरा डेटाबेस को वास्तविक क्वेरी भेजकर पुष्टि करता है कि वह पहुँच योग्य है। ट्रैफ़िक भेजा जाए या नहीं, यह केवल दूसरा तय करता है।
- ब्राउज़र ऑरिजिन एक सूची तक सीमित हैंक्रॉस-ऑरिजिन अनुरोध केवल उन्हीं ऑरिजिन से स्वीकार होते हैं जो पहले से घोषित हों; जब तक सूची खाली है, ब्राउज़र का क्रॉस-ऑरिजिन अनुरोध अस्वीकार होता है।
- मुख्य भाग की सीमाअनुरोध का मुख्य भाग पाँच मेगाबाइट से अधिक नहीं हो सकता। बड़े समूह एकल अनुरोध के रूप में नहीं, बल्कि अपनी स्थिति रिकॉर्ड वाले थोक हस्तांतरण कार्य के रूप में जाते हैं।
- गोपनीय मान लॉग में नहीं लिखे जातेसर्वर लॉग में न authorization हेडर रखा जाता है, न कुकी, न पासवर्ड, न राष्ट्रीय पहचान संख्या।
दर सीमा
सीमा प्रति पता और प्रति मिनट है। डिफ़ॉल्ट 120 अनुरोध प्रति मिनट है और यह परिनियोजन के समय तय होता है। कितना शेष है, यह हर उत्तर के हेडर में बताया जाता है।
| उत्तर हेडर | यह क्या बताता है |
|---|---|
| x-ratelimit-limit | विंडो के भीतर कुल स्वीकृत मात्रा। |
| x-ratelimit-remaining | इस विंडो में कितना शेष है। |
| x-ratelimit-reset | स्वीकृत मात्रा नवीनीकृत होने तक के सेकंड। |
| retry-after | दोबारा प्रयास से पहले कितने सेकंड। केवल उसी उत्तर में होता है जिसने अनुरोध अस्वीकार किया। |
सीमा पार होते ही अनुरोध अस्वीकार कर दिया जाता है और उत्तर सेकंड में बताता है कि कितनी देर प्रतीक्षा करनी है। दोबारा प्रयास उसी समय के बाद किया जाता है, तुरंत नहीं।
त्रुटि का प्रारूप
हर त्रुटि एक ही लिफ़ाफ़े में लौटती है: मशीन के निर्णय के लिए एक छोटा कोड फ़ील्ड, और व्यक्ति के पढ़ने के लिए एक विवरण फ़ील्ड।
- errorछोटा कोड जिस पर क्लाइंट निर्णय लेता है।
- messageक्या हुआ, उसका विवरण।
| स्थिति | कोड फ़ील्ड | इसका अर्थ |
|---|---|---|
| 400 | Bad Request | अनुरोध स्कीमा से मेल नहीं खाता। विवरण में उस फ़ील्ड का नाम होता है जो अनुपस्थित या अमान्य है। |
| 401 | unauthenticated | कोई वैध पहचान नहीं है: टोकन भेजा ही नहीं गया, समाप्त हो चुका है, या सत्यापित नहीं हुआ। |
| 404 | Not Found | ऐसा कोई एंडपॉइंट नहीं, या ऐसा कोई रिकॉर्ड नहीं। |
| 429 | Too Many Requests | दर सीमा पार हो गई; उत्तर बताता है कि कितनी देर प्रतीक्षा करनी है। |
| 5xx | internal_error | एक अप्रत्याशित विफलता। विवरण क्लाइंट को नहीं सौंपा जाता; वह सर्वर लॉग में लिखा जाता है। |
पृष्ठ-विभाजन
सूची लौटाने वाले एंडपॉइंट वही दो पैरामीटर लेते हैं और वही गणक लौटाते हैं, इसलिए पेजिंग करने वाला क्लाइंट हर एंडपॉइंट के लिए दोबारा नहीं लिखा जाता।
- limitएक पृष्ठ में कितने रिकॉर्ड होने चाहिए। कम से कम एक, अधिकतम दो सौ; निर्धारित न हो तो पचास।
- offsetकितने रिकॉर्ड छोड़ने हैं। शून्य से शुरू होता है।
- totalफ़िल्टर से कुल कितने रिकॉर्ड मेल खाते हैं।
- countयह उत्तर वास्तव में कितने रिकॉर्ड ले जा रहा है।
उत्तर उपयोग किए गए limit और offset को भी दोहराता है; क्लाइंट अपनी स्थिति अनुमान से नहीं, उत्तर से पढ़ता है।
डेटा विनिमय और webhook
विनिमय का प्रकार एक सेटिंग है, अलग उत्पाद नहीं: हर पंजीकृत ऐप्लिकेशन अपने रिकॉर्ड पर वह प्रकार रखता है जिसमें वह काम करता है।
| प्रकार | इसका अर्थ |
|---|---|
| एकदिश — बाहर की ओर | Optifora डेटा प्रकाशित करता है; दूसरा पक्ष उसे पढ़ता है या घटनाओं की सदस्यता लेता है। |
| एकदिश — भीतर की ओर | दूसरा पक्ष डेटा भेजता है; Optifora उसे जाँचकर लिखता है। |
| द्विदिश | दोनों पक्ष लिखते हैं; टकराव का नियम पहले से तय होता है। |
| हस्तमिलाप | हर हस्तांतरण एक सत्र खोलता है: प्रस्ताव, सत्यापन, स्वीकृति, हस्तांतरण और रसीद। रसीद दोनों पक्षों के पास रहती है। |
- घटनाएँ बाहर भेजी जाती हैंwebhook घटना को उस कॉलबैक पते पर भेजता है जो पंजीकृत ऐप्लिकेशन ने घोषित किया है। जो घटना पहुँचाई न जा सके वह कतार में रहती है और दोबारा भेजी जाती है; उसे कभी चुपचाप गिराया नहीं जाता।
- एक ही अनुरोध दो बार नहीं लिखतालिखने वाला अनुरोध एक idempotency कुंजी रखता है। उसी कुंजी वाला दूसरा अनुरोध दूसरा रिकॉर्ड नहीं बनाता।
- हर कॉल मापी जाती हैकिसने कॉल किया, कब, किस दायरे में और किस परिणाम के साथ — सब दर्ज होता है। यही रिकॉर्ड दोष-निवारण का भी उत्तर देता है और इस प्रश्न का भी कि यह डेटा किसने खींचा।
- हमारे अपने ऐप भी वही दरवाज़ा इस्तेमाल करते हैंकोई विशेषाधिकार वाला दूसरा रास्ता नहीं है। हमारा अपना एकीकरण ही इस बात का प्रमाण है कि बाहरी डेवलपर को कैसी सतह मिलती है।
विनिमय परत का डेटा मॉडल तैयार है; उसके एंडपॉइंट अभी प्रकाशित नहीं हुए। जब होंगे, तब यह अनुभाग संदर्भ में उनकी प्रविष्टियों से जुड़ जाएगा।
संदर्भ दस्तावेज़
संदर्भ हाथ से नहीं लिखा जाता; वह एंडपॉइंट स्कीमा से उत्पन्न होता है। जैसे-जैसे हर एंडपॉइंट अपनी स्कीमा सौंपता है, दस्तावेज़ स्वयं भरता जाता है, इसलिए दस्तावेज़ और व्यवहार एक-दूसरे से अलग नहीं हो सकते।
- आज: तैयारी मेंस्कीमा मॉड्यूल दर मॉड्यूल आगे बढ़ रही हैं। दस्तावेज़ प्रकाशित होने से पहले हर एंडपॉइंट का अनुरोध और उत्तर उसमें दिखाई देगा।
- दो प्रारूप प्रकाशित होंगेएक मशीन-पठनीय OpenAPI दस्तावेज़, और उसी दस्तावेज़ से बना एक संदर्भ पृष्ठ जिसे ब्राउज़र में देखा जा सके।
- पहुँच स्तरों में बँटी हैसिंहावलोकन सबके लिए खुला है। पूरा संदर्भ किसी पंजीकृत इंटीग्रेटर को दिए गए दस्तावेज़ टोकन के पीछे हो सकता है; उत्पादन कुंजियाँ और कॉलबैक पते दस्तावेज़ का विषय ही नहीं हैं — वे ऐप्लिकेशन रिकॉर्ड से जुड़े हैं।
- पते का मानकदो संदर्भ प्रकाशित होते हैं और उनके पते निश्चित हैं: client-api.optifora.com/docs खुला है, admin-api.optifora.com/docs के लिए अधिकार आवश्यक है और वह बाहर के लिए बंद है। आज दोनों में से कोई सक्रिय नहीं है; सक्रिय होते ही लिंक इसी अनुभाग में जोड़ दिए जाएँगे।
यदि आपकी एकीकरण योजना पहले से स्पष्ट है, तो संपर्क पृष्ठ से हमें लिखिए: सतह खुलते ही सबसे पहले सूचित होने वालों में आप होंगे।
क्या आपका कोई विशेष अनुरोध है?
ये पृष्ठ बताते हैं कि सहायता प्रक्रिया कैसे चलती है। आपका कोई अनुरोध या प्रश्न हो तो संपर्क पृष्ठ से हमें लिखिए।
संपर्क पृष्ठ पर जाएँ