👩‍🚒 🎰 🎯 एपीआई के एक नए संस्करण में प्रवासन 👨🏾‍🎤 🌀 🗽

मोते-मॉरिस हाउस ले जाना: लेसेबर्ग, फ्लोरिडा

हमारे एपीआई के पहले संस्करण का जीवनकाल एक करीबी के लिए ड्राइंग है। उन लोगों के लिए जिन्होंने अभी तक अपने अनुप्रयोगों को नए संस्करण में माइग्रेट नहीं किया है, हमने एक माइग्रेशन गाइड तैयार किया है।

सबसे खास बात यह है कि नए वर्जन में एक्सएमएल नहीं है। हां, हमने केवल JSON छोड़ दिया, लेकिन यह सब नहीं है।

बाकी

एपीआई को डिजाइन करते समय, हमने URL का नामकरण और HTTP प्रोटोकॉल की क्षमताओं का उपयोग करते हुए REST दृष्टिकोण का पालन किया।

संक्षेप में, हमारे एपीआई के उत्तर में, मानक 200, 302, 403, 404 और 500 स्थितियों के अलावा, आप देख सकते हैं: 201, 204, 405, 429, 503 और कुछ अन्य। एपीआई क्लाइंट को उन्हें सही ढंग से संसाधित करने में सक्षम होना चाहिए: 429 और / या 400 पर अर्थहीन पुनरावृत्ति न करें और 503 प्राप्त करने से न चूकें।

URL का नामकरण करते समय, हमने "संग्रह" और "संग्रह तत्व" शब्दों का उपयोग किया, और सीधे HTTP विधियों का उपयोग करके क्रियाओं को व्यक्त किया।

अब, रिक्तियों की खोज करने के लिए /1/json/vacancy/search/ बजाय, जॉब्स संग्रह का पता प्रकट हुआ है: /vacancies ।

इस पते पर GET अनुरोध करने के बाद, आप क्वेरी मापदंडों को निर्दिष्ट करके संपूर्ण संग्रह (साइट पर सभी रिक्तियां) और किसी प्रकार का टुकड़ा GET /vacancies?text= सकते हैं: GET /vacancies?text= । `टेक्स्ट` पैरामीटर को निर्दिष्ट करके, हमने फ़िल्टर को संग्रह पर लागू किया और इस तरह रिक्तियों के लिए खोज परिणाम प्राप्त किए।

एक ही नाम के प्रलेखन खंड में मापदंडों की एक पूरी सूची उपलब्ध है।

आप संग्रह का एक अलग तत्व प्राप्त कर सकते हैं, इस मामले में रिक्ति: GET /vacancies/7760476 ।

एक संग्रह संसाधन में सबकोलिलेशन भी हो सकते हैं, पूरे संग्रह के कुछ पूर्वनिर्धारित स्लाइस। GET /vacancies/favorited उन रिक्तियों को एक अधिकृत उपयोगकर्ता द्वारा "चयनित" लोगों के लिए जोड़ा जाता है।

"चयनित" के लिए एक रिक्ति जोड़ने के लिए, आपको एक उपयुक्त उपकुंजी में रिक्ति जोड़ने की आवश्यकता है:

PUT /vacancies/favorited/{vacancy_id}

निकालने के लिए, आपको इसे इस संग्रह से निकालना होगा।

DELETE /vacancies/favorited/{vacancy_id}

PUT और DELETE अनुरोध निष्प्राण हैं: यदि आप किसी रिक्ति को "चयनित" करने का प्रयास करते हैं जो पहले से चयनित लोगों में है, तो PUT 204 पर वापस आ जाएगा, जिससे उत्तर दिया जाएगा: "क्या आप चाहते हैं कि यह रिक्ति चयनित हो? कोई समस्या नहीं। वह चयनित है। ” भले ही वह पहले से ही वहां था। विलोपन के साथ भी।

एक रिक्ति बनाने के लिए (यह कार्यक्षमता अभी तक लागू नहीं हुई है, लेकिन योजनाबद्ध है), यह आवश्यक है कि POST /vacancies , जो शरीर में निर्मित रिक्ति के मापदंडों को दर्शाता है। POST और PUT के बीच मुख्य अंतर यह है कि पहला बेकार नहीं है, अर्थात जब आप पुनः अनुरोध करते हैं, तो एक और रिक्ति बनाने का प्रयास होगा।

नतीजतन: HTTP विधियों, HTTP कोड और नामकरण URL का सही और व्यापक उपयोग अवधारणाओं के अनुसार: संग्रह, सबकोलेशन और संग्रह तत्व - हमारी समझ में, REST है।

संग्रह और संग्रह

संग्रह के बारे में थोड़ा और। सभी संग्रह जो पृष्ठांकन का समर्थन करते हैं (फिर से शुरू, रिक्तियां, कंपनियां और उनके सभी सबकोक्लेक्शन) एक जैसे दिखते हैं और उनके पास प्रपत्र का मूल उद्देश्य है:

 { "found": 0, "per_page": 20, "page": 0, "pages": 1, "items": [] }

किसी भी संग्रह के अनुरोध के लिए, आप पैरामीटर में पेज = एन एंड पे_पेज = एम निर्दिष्ट कर सकते हैं। क्रमांकन खरोंच से शुरू होता है, डिफ़ॉल्ट रूप से, पहला (शून्य) पृष्ठ प्रति पृष्ठ 20 ऑब्जेक्ट के साथ जारी किया जाता है।

वर्ज़निंग

हमने संस्करण निकाल दिया, एपीआई का अब पते में कोई उपसर्ग नहीं है: /1/... सभी URL रूट से चलते हैं: api.hh.ru/dictionaries api.hh.ru/dictionaries । समय के साथ, डेटा का विस्तार होगा, हमेशा पिछड़े अनुकूलता प्रदान करेगा। केवल दो मामलों में इस नियम के अपवाद हो सकते हैं:

एक महत्वपूर्ण दोष का सुधार: एक त्रुटि रिलीज में, या शायद यहां तक कि प्रकाशित प्रलेखन में भी ठीक हो जाएगी, जिसे सही करते हुए हमें डेटा प्रारूप बदलना होगा।
व्यावसायिक तर्क में बदलाव के कारण एपीआई को बंद करना: hh.ru एक रिक्ति डेटाबेस प्रदान करना बंद कर देगा, हम साइट पर प्रतिक्रियाओं को एक सेवा और अन्य अविश्वसनीय, शानदार मामलों के रूप में गायब कर देंगे जब हम सैद्धांतिक रूप से आउटपुट डेटा के प्रारूप का समर्थन नहीं कर सकते।

कम हार्डकोड

उस स्थान पर जहां हम उस मूल्य को देते हैं जो हमारे एपीआई में उपलब्ध इकाई का प्रतिनिधित्व करता है, हम आपको आपके आवेदन में दिए पते को "हार्डकोड" करने की आवश्यकता से बचाने के लिए एक पूर्ण लिंक प्रदान करते हैं।
उदाहरण के लिए, नौकरी की तलाश में:

 { "items": [ { "url": "https://api.hh.ru/vacancies/1337" } ] }

खोज परिणाम प्राप्त करने के बाद, आपको रिक्ति के बारे में पूरी जानकारी प्राप्त करने के लिए एक लिंक का निर्माण करने की आवश्यकता नहीं है, आपको केवल url कुंजी मान लेने की आवश्यकता है।

रिक्तियों को खोजें और देखें

अब डेटा के बारे में ही। हमारे एपीआई का मुख्य और सबसे लोकप्रिय उपयोग रिक्तियों की खोज और वितरण है।
यह पहले /1/json/vacancy/search/ और /1/json/vacancy/{vacancy_id} क्रमशः उपलब्ध था। अब, REST दृष्टिकोण के बाद, हमने इसे / रिक्तियों के संग्रह में जोड़ दिया है।

खोज करने के लिए, आपको आवश्यक क्वेरी मापदंडों को पारित करके संसाधन के लिए एक GET अनुरोध करने की आवश्यकता है। एक अलग रिक्ति प्राप्त करने के लिए, अलग तत्व के लिए एक GET अनुरोध GET /vacancies/7760476 : GET /vacancies/7760476 ( https://api.hh.ru/vacancies/7760476) ।

इसके अलावा, इससे पहले कि हम एक विशेष कंपनी के लिए रिक्तियों को प्राप्त करने के लिए एक अलग पता था, अब यह एक खोज के माध्यम से उपलब्ध है: GET /vacancies?employer_id=1455 https://api.hh.ru/vacancies?employer_id/1455;

संदर्भ

खोज अनुरोध करने के लिए, साथ ही उत्तरों को समझने के लिए, हम अपनी संस्थाओं की निर्देशिकाएं जारी करते हैं: रोजगार का प्रकार, कार्य अनुसूची, मुद्रा, कार्य अनुभव। यह व्यक्तिगत पते पर उपलब्ध होता था:

GET /1/json/employment/
GET /1/json/schedule/
GET /1/json/experience/
GET /1/json/currency/

अब हमने इन सभी छोटी निर्देशिकाओं को एक संसाधन `/dictionaries` api.hh.ru/d `/dictionaries` जोड़ा है । (प्रलेखन में वर्णन: github.com/hhru/api/blob/master/docs/dmail.md )।

हमने अलग-अलग निर्देशिकाओं को अलग-अलग पते पर बड़ी संख्या में अर्थ ( विशेषज्ञता , क्षेत्र , मेट्रो ) युक्त छोड़ दिया:

GET /specializations - api.hh.ru/specialifications
GET /metro - api.hh.ru/metro
GET /areas - api.hh.ru/areas

विशेषज्ञता को पेशेवर क्षेत्रों के साथ जोड़ा गया था (पहले यह दो अलग-अलग पते थे: क्षेत्र और विशेषज्ञता)।
क्षेत्रों का नाम बदलकर /areas - api.hh.ru/areas कर दिया गया।

प्राधिकरण और नई सेवाएं

लेकिन हेडहंटर एपीआई नौकरी खोजों और संबंधित निर्देशिकाओं तक सीमित नहीं है। नए संस्करण में, प्राधिकरण , देखने की प्रतिक्रियाएं और बहुत कुछ उपलब्ध हैं। यह प्रवासन पर लेख के दायरे से परे है, लेकिन इन सभी तरीकों का विवरण हमारे प्रलेखन में उपलब्ध है। पढ़ें, कोशिश करें, हमें लिखें, देखते रहें!

एपीआई के एक नए संस्करण में प्रवासन