पायथन में लिखे HTTP एपीआई के प्रकार: इंस्टाग्राम अनुभव

आज हम Instagram में पायथन के उपयोग के लिए समर्पित श्रृंखला से दूसरी सामग्री प्रकाशित कर रहे हैं। पिछली बार यह इंस्टाग्राम सर्वर कोड के प्रकारों की जाँच कर रहा था। सर्वर पायथन में लिखा एक मोनोलिथ है। इसमें कई मिलियन लाइनों के कोड होते हैं और इसमें कई हजार Django के समापन बिंदु होते हैं।



यह आलेख इस बारे में है कि इंस्टाग्राम HTTP एपीआई को दस्तावेज़ करने और उनके साथ काम करने के दौरान अनुबंधों को लागू करने के लिए किस प्रकार का उपयोग करता है।

स्थिति अवलोकन

जब आप Instagram मोबाइल क्लाइंट खोलते हैं, तो यह HTTP प्रोटोकॉल के माध्यम से, हमारे पायथन (Django) सर्वर के JSON-API तक पहुँचता है।

हमारे सिस्टम के बारे में कुछ जानकारी यहां दी गई है जिससे आप एपीआई की जटिलता का अंदाजा लगा पाएंगे जिसका उपयोग हम मोबाइल क्लाइंट के काम को व्यवस्थित करने के लिए करते हैं। तो यहाँ हमारे पास है:

• सर्वर पर 2000 से अधिक समापन बिंदु।
• क्लाइंट डेटा ऑब्जेक्ट में 200 से अधिक शीर्ष-स्तरीय फ़ील्ड जो किसी एप्लिकेशन में एक छवि, वीडियो या कहानी का प्रतिनिधित्व करता है।
• सैकड़ों प्रोग्रामर जो सर्वर कोड लिखते हैं (और इससे भी अधिक जो क्लाइंट से निपटते हैं)।
• सर्वर कोड के सैकड़ों आवागमन रोजाना किए जाते हैं और एपीआई को संशोधित करते हैं। यह नई प्रणाली सुविधाओं के लिए सहायता प्रदान करना है।

हम अपने कॉम्प्लेक्स को निरंतर रूप से विकसित करने के लिए, HTTP APIs को विकसित करने और उनके साथ काम करते समय अनुबंधों को लागू करने के लिए प्रकारों का उपयोग करते हैं।

प्रकार

चलिए शुरू से ही शुरू करते हैं। पायथन कोड में टाइप एनोटेशन के लिए वाक्यविन्यास का वर्णन पीईपी 484 में दिखाई दिया। कोड में टाइप एनोटेशन क्यों जोड़ें?

उस फ़ंक्शन पर विचार करें जो स्टार वार्स के नायक के बारे में जानकारी डाउनलोड करता है:

def get_character(id, calendar):     if id == 1000:         return Character(             id=1000,             name="Luke Skywalker",             birth_year="19BBY" if calendar == Calendar.BBY else ...         )     ... 

इस फ़ंक्शन को समझने के लिए, आपको इसके कोड को पढ़ने की आवश्यकता है। ऐसा करने के बाद, आप निम्नलिखित पता लगा सकते हैं:

• यह वर्ण का पूर्णांक पहचानकर्ता ( id ) लेता है।
• यह इसी गणना ( calendar ) से मूल्य लेता है। उदाहरण के लिए, Calendar.BBY अर्थ "यवन के युद्ध से पहले" है, अर्थात "यवन के युद्ध से पहले।"
• यह इस चरित्र के पहचानकर्ता, उसके नाम और जन्म के वर्ष का प्रतिनिधित्व करने वाले क्षेत्र के रूप में एक इकाई के रूप में चरित्र के बारे में जानकारी देता है।

फ़ंक्शन का एक अंतर्निहित अनुबंध होता है, जिसका अर्थ प्रोग्रामर को हर बार बहाल करना होता है जब वह फ़ंक्शन कोड पढ़ता है। लेकिन फ़ंक्शन कोड केवल एक बार लिखा गया है, और आपको इसे कई बार पढ़ना होगा, इसलिए इस कोड के साथ काम करने का यह तरीका विशेष रूप से अच्छा नहीं है।

इसके अलावा, यह सत्यापित करना मुश्किल है कि फ़ंक्शन को कॉल करने वाला तंत्र ऊपर वर्णित अंतर्निहित अनुबंध का पालन करता है। इसी तरह, यह सत्यापित करना मुश्किल है कि यह अनुबंध फ़ंक्शन के शरीर में सम्मानित है। एक बड़े कोड बेस में, ऐसी स्थितियां त्रुटियों को जन्म दे सकती हैं।

अब उसी फ़ंक्शन पर विचार करें जो टाइप एनोटेशन घोषित करता है:

 def get_character(id: int, calendar: Calendar) -> Character:    ... 

टाइप एनोटेशन आपको इस फ़ंक्शन के अनुबंध को स्पष्ट रूप से व्यक्त करने की अनुमति देते हैं। यह समझने के लिए कि किसी फ़ंक्शन के लिए इनपुट की आवश्यकता क्या है, और यह फ़ंक्शन क्या देता है, बस इसके हस्ताक्षर को पढ़ें। एक प्रकार की जाँच प्रणाली स्टेटिक रूप से फ़ंक्शन का विश्लेषण कर सकती है और कोड में अनुबंध का अनुपालन सत्यापित कर सकती है। यह आपको त्रुटियों की एक पूरी कक्षा से छुटकारा पाने की अनुमति देता है!

विभिन्न HTTP एपीआई के लिए प्रकार

हम एक HTTP-API विकसित करेंगे जो आपको स्टार वार्स के नायकों के बारे में जानकारी प्राप्त करने की अनुमति देता है। इस एपीआई के साथ काम करते समय उपयोग किए जाने वाले स्पष्ट अनुबंध का वर्णन करने के लिए, हम टाइप एनोटेशन का उपयोग करेंगे।

हमारे एपीआई को एक URL पैरामीटर के रूप में चरित्र पहचानकर्ता ( id ) और एक अनुरोध पैरामीटर के रूप में calendar गणना के मूल्य को स्वीकार करना चाहिए। एपीआई को चरित्र की जानकारी के साथ JSON प्रतिक्रिया वापस करनी चाहिए।

यहाँ API अनुरोध कैसा दिखता है और प्रतिक्रिया यह देता है:

 curl -X GET https://api.starwars.com/characters/1000?calendar=BBY {    "id": 1000,    "name": "Luke Skywalker",    "birth_year": "19BBY" } 

Django में इस एपीआई को लागू करने के लिए, आपको सबसे पहले URL पथ और इस पथ के साथ किए गए HTTP अनुरोध प्राप्त करने और प्रतिक्रिया वापस करने के लिए जिम्मेदार प्रस्तुति फ़ंक्शन को पंजीकृत करने की आवश्यकता है।

 urlpatterns = [    url("characters/<id>/", get_character) ] 

इनपुट के रूप में फ़ंक्शन अनुरोध और URL पैरामीटर (हमारे मामले में, id ) को स्वीकार करता है। यह calendar अनुरोध पैरामीटर को पार्स और कास्ट करता है, जो कि आवश्यक गणना के लिए संबंधित गणना से मूल्य है। यह स्टोर से वर्ण डेटा लोड करता है और JSON में क्रमबद्ध एक शब्दकोश देता है और HTTP प्रतिक्रिया में लिपटा होता है।

 def get_character(request: IGWSGIRequest, id: str) -> JsonResponse:    calendar = Calendar(request.GET.get("calendar", "BBY"))    character = Store.get_character(id, calendar)    return JsonResponse(asdict(character)) 

यद्यपि फ़ंक्शन प्रकार एनोटेशन के साथ प्रदान किया गया है, यह स्पष्ट रूप से HTTP एपीआई के लिए कठिन अनुबंध का वर्णन नहीं करता है। इस फ़ंक्शन के हस्ताक्षर से हम नाम या प्रकार के अनुरोध मापदंडों, या प्रतिक्रिया क्षेत्रों और उनके प्रकारों का पता नहीं लगा सकते हैं।

क्या यह संभव है कि फ़ंक्शन-प्रतिनिधित्व के हस्ताक्षर को वैसा ही जानकारीपूर्ण बनाया जाए जो प्रकार एनोटेशन के साथ पहले से माना गया फ़ंक्शन का हस्ताक्षर है?

 def get_character(id: int, calendar: Calendar) -> Character:    ... 

फ़ंक्शन पैरामीटर क्वेरी पैरामीटर (URL, क्वेरी या क्वेरी बॉडी पैरामीटर) हो सकते हैं। फ़ंक्शन द्वारा लौटाए गए मान का प्रकार प्रतिक्रिया की सामग्री का प्रतिनिधित्व कर सकता है। इस दृष्टिकोण के साथ, हमारे पास HTTP एपीआई के लिए एक स्पष्ट और समझने योग्य अनुबंध होगा, जिसका पालन एक प्रकार की जाँच प्रणाली द्वारा सुनिश्चित किया जा सकता है।

कार्यान्वयन

इस विचार को कैसे लागू किया जाए?

हम एक डेकोरेटर का उपयोग एक दृढ़ता से टाइप किए गए प्रतिनिधित्व फ़ंक्शन को Django प्रतिनिधित्व फ़ंक्शन में बदलने के लिए करते हैं। इस कदम को Django ढांचे के साथ काम करने के संदर्भ में परिवर्तन की आवश्यकता नहीं है। हम उसी मिडलवेयर, समान मार्गों और अन्य घटकों का उपयोग कर सकते हैं जिनका हम उपयोग करते हैं।

 @api_view def get_character(id: int, calendar: Calendar) -> Character:    ... 

api_view डेकोरेटर api_view के विवरण पर विचार करें:

 def api_view(view):    @functools.wraps(view)    def django_view(request, *args, **kwargs):        params = {            param_name: param.annotation(extract(request, param))            for param_name, param in inspect.signature(view).parameters.items()        }        data = view(**params)        return JsonResponse(asdict(data))       return django_view 

यह समझने के लिए कोड का एक कठिन टुकड़ा है। आइए इसकी विशेषताओं का विश्लेषण करते हैं।
हम, इनपुट मूल्य के रूप में, एक दृढ़ता से टाइप किए गए प्रतिनिधित्व फ़ंक्शन को लेते हैं और इसे एक नियमित Django प्रतिनिधित्व फ़ंक्शन में लपेटते हैं, जिसे हम वापस करते हैं:

 def api_view(view):    @functools.wraps(view)    def django_view(request, *args, **kwargs):        ...    return django_view 

अब Django दृश्य फ़ंक्शन के कार्यान्वयन पर एक नज़र डालें। पहले हमें एक दृढ़ता से टाइप की गई प्रस्तुति फ़ंक्शन के लिए तर्क का निर्माण करने की आवश्यकता है। हम इस फ़ंक्शन के हस्ताक्षर प्राप्त करने और इसके मापदंडों पर पुनरावृति प्राप्त करने के लिए आत्मनिरीक्षण और निरीक्षण मॉड्यूल का उपयोग करते हैं:

 for param_name, param in inspect.signature(view).parameters.items() 

प्रत्येक पैरामीटर के लिए, हम extract फ़ंक्शन को कॉल करते हैं, जो अनुरोध से पैरामीटर मान निकालता है।

फिर हम हस्ताक्षर में निर्दिष्ट अपेक्षित प्रकार के पैरामीटर को डालते हैं (उदाहरण के लिए, स्ट्रिंग calendar को उस मूल्य पर निर्दिष्ट करें जो Calendar गणना का एक तत्व है)।

 param.annotation(extract(request, param)) 

हम अपने द्वारा निर्मित तर्कों के साथ एक दृढ़ता से टाइप किए गए दृश्य फ़ंक्शन को कॉल करते हैं:

 data = view(**params) 

फ़ंक्शन Character वर्ग का एक ज़ोरदार टाइप किया गया मान देता है। हम इसे मान लेते हैं, इसे एक शब्दकोश में बदलते हैं और इसे JSON प्रारूप HTTP प्रतिसाद में लपेटते हैं:

 return JsonResponse(asdict(data)) 

बहुत बढ़िया! अब हमारे पास एक Django दृश्य फ़ंक्शन है जो दृढ़ता से टाइप किए गए दृश्य फ़ंक्शन को लपेटता है। अंत में, extract कार्य पर एक नज़र डालें:

 def extract(request: HttpRequest, param: Parameter) -> Any:    if request.resolver_match.route.contains(f"<{param}>"):        return request.resolver_match.kwargs.get(param.name)    else:        return request.GET.get(param.name) 

प्रत्येक पैरामीटर एक URL पैरामीटर या एक अनुरोध पैरामीटर हो सकता है। अनुरोध URL पथ (वह पथ जिसे हमने शुरुआत में पंजीकृत किया था) जो Django URL लोकेटर सिस्टम के रूट ऑब्जेक्ट में उपलब्ध है। हम पथ में पैरामीटर नाम की जांच करते हैं। यदि कोई नाम है, तो हमारे पास एक URL पैरामीटर है। इसका मतलब है कि हम किसी भी तरह से इसे अनुरोध से निकाल सकते हैं। अन्यथा, यह एक क्वेरी पैरामीटर है और हम इसे निकाल भी सकते हैं, लेकिन किसी अन्य तरीके से।

वह सब है। यह एक सरलीकृत कार्यान्वयन है, लेकिन यह एपीआई टाइप करने के मूल विचार को दिखाता है।

डेटा प्रकार

HTTP प्रतिसाद (यानी, Character ) की सामग्री का प्रतिनिधित्व करने के लिए उपयोग किए जाने वाले प्रकार को डेटाक्लास या टाइपिंग शब्दकोश द्वारा प्रस्तुत किया जा सकता है।

एक डेटा वर्ग एक कॉम्पैक्ट क्लास विवरण प्रारूप है जो डेटा का प्रतिनिधित्व करता है।

 from dataclasses import dataclass @dataclass(frozen=True) class Character:    id: int    name: str    birth_year: str luke = Character(    id=1000,    name="Luke Skywalker",    birth_year="19BBY" ) 

Instagram आमतौर पर HTTP प्रतिक्रिया वस्तुओं को मॉडल करने के लिए डेटा कक्षाओं का उपयोग करता है। यहाँ उनकी मुख्य विशेषताएं हैं:

• वे स्वतः टेम्पलेट निर्माण और विभिन्न सहायक विधियाँ उत्पन्न करते हैं।
• वे चेकिंग सिस्टम टाइप करने के लिए समझ में आते हैं, जिसका अर्थ है कि मान टाइप चेक के अधीन हो सकते हैं।
• वे frozen=True निर्माण के लिए प्रतिरक्षा को बनाए रखते हैं।
• वे पायथन मानक पुस्तकालय 3.7, या पायथन पैकेज इंडेक्स में एक बैकपोर्ट के रूप में उपलब्ध हैं।

दुर्भाग्य से, Instagram के पास एक पुराना कोड आधार है जो फ़ंक्शन और मॉड्यूल के बीच पारित किए गए बड़े, अनकैप्ड शब्दकोशों का उपयोग करता है। शब्दकोश से डेटा कक्षाओं में इस सभी कोड का अनुवाद करना आसान नहीं होगा। नतीजतन, हम, नए कोड के लिए डेटा कक्षाओं का उपयोग कर रहे हैं, और पुराने कोड में हम टाइप किए गए शब्दकोशों का उपयोग करते हैं।

टाइप किए गए शब्दकोशों का उपयोग करने से हमें क्लाइंट शब्दकोश ऑब्जेक्ट में टाइप एनोटेशन जोड़ने की अनुमति मिलती है और, एक कार्य प्रणाली के व्यवहार को बदलने के बिना, टाइपिंग क्षमताओं का उपयोग करें।

 from mypy_extensions import TypedDict class Character(TypedDict):    id: int    name: str    birth_year: str luke: Character = {"id": 1000} luke["name"] = "Luke Skywalker" luke["birth_year"] = 19 # type error, birth_year expects a str luke["invalid_key"] # type error, invalid_key does not exist 

हैंडलिंग में त्रुटि

वर्ण फ़ंक्शन को Character इकाई के रूप में वर्ण जानकारी वापस करने की अपेक्षा की जाती है। यदि हमें क्लाइंट को कोई त्रुटि वापस करने की आवश्यकता है तो हमें क्या करना चाहिए?

आप एक अपवाद फेंक सकते हैं जिसे फ्रेमवर्क द्वारा पकड़ा जाएगा और त्रुटि सूचना के साथ HTTP प्रतिक्रिया में परिवर्तित किया जाएगा।

 @api_view("GET") def get_character(id: str, calendar: Calendar) -> Character:    try:        return Store.get_character(id)    except CharacterNotFound:        raise Http404Exception() 

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

उपकरण

HTTP API, HTTP मेथड, रिक्वेस्ट टाइप्स और रिस्पांस टाइप्स का उपयोग करके दृढ़ता से टाइप किया जाता है। हम इस एपीआई को आत्मसात कर सकते हैं और यह निर्धारित कर सकते हैं कि इसे URL पथ में id स्ट्रिंग के साथ और क्वेरी स्ट्रिंग में संबंधित गणन से संबंधित calendar मान के साथ एक GET अनुरोध स्वीकार करना चाहिए। हम यह भी सीख सकते हैं कि ऐसे अनुरोध के जवाब में Character की प्रकृति के बारे में जानकारी के साथ एक JSON प्रतिक्रिया दी जानी चाहिए।

इस सारी जानकारी के साथ क्या किया जा सकता है?

OpenAPI एक एपीआई विवरण प्रारूप है जिसके आधार पर सहायक उपकरणों का एक समृद्ध सेट बनाया गया है। यह एक संपूर्ण पारिस्थितिकी तंत्र है। यदि हम एंडपॉइंट आत्मनिरीक्षण करने के लिए कुछ कोड लिखते हैं और प्राप्त आंकड़ों के आधार पर ओपनएपीआई विनिर्देशों को उत्पन्न करते हैं, तो इसका मतलब होगा कि हमारे पास इन उपकरणों की क्षमताएं होंगी।

 paths:  /characters/{id}:    get:      parameters:        - in: path          name: id          schema:            type: integer          required: true        - in: query          name: calendar          schema:            type: string            enum: ["BBY"]      responses:        '200':          content:            application/json:              schema:                type: object                ... 

हम get_character API के लिए HTTP API डॉक्यूमेंट जनरेट कर सकते हैं, जिसमें नाम, प्रकार, अनुरोध और प्रतिक्रिया की जानकारी शामिल है। यह क्लाइंट डेवलपर्स के लिए अमूर्त स्तर का एक उपयुक्त स्तर है जिन्हें उचित समापन बिंदु के लिए अनुरोधों को पूरा करने की आवश्यकता होती है। उन्हें इस समापन बिंदु के लिए पायथन कार्यान्वयन कोड को पढ़ने की आवश्यकता नहीं है।


एपीआई प्रलेखन

इस आधार पर, आप अतिरिक्त टूल बना सकते हैं। उदाहरण के लिए, एक ब्राउज़र से एक अनुरोध को निष्पादित करने का साधन। यह डेवलपर्स को बिना कोड लिखने के लिए बिना उनकी रुचि के HTTP API तक पहुंचने की अनुमति देता है। हम यह भी सुनिश्चित कर सकते हैं कि टाइप-सेफ़ क्लाइंट कोड यह सुनिश्चित करने के लिए कि क्लाइंट और सर्वर दोनों पर सही तरीके से काम हो। इसके कारण, हम अपने निपटान में सर्वर पर एक कड़ाई से टाइप किए गए एपीआई, कॉल कर सकते हैं, जो कड़ाई से टाइप किए गए क्लाइंट कोड का उपयोग करके किया जाता है।

इसके अलावा, हम एक बैकवर्ड कम्पैटिबिलिटी चेक सिस्टम बना सकते हैं। यदि हम सर्वर कोड का एक नया संस्करण जारी करते हैं जिसमें एपीआई का उपयोग करने के लिए हमें id , name और birth_year name का उपयोग करने की आवश्यकता birth_year , और तब हम समझते हैं कि हम सभी पात्रों के जन्मदिन नहीं जानते हैं? इस स्थिति में, birth_year पैरामीटर birth_year वैकल्पिक बनाने की आवश्यकता birth_year , लेकिन समान पैरामीटर की अपेक्षा करने वाले क्लाइंट के पुराने संस्करण बस काम करना बंद कर सकते हैं। यद्यपि हमारे एपीआई स्पष्ट टाइपिंग में भिन्न हैं, लेकिन संबंधित प्रकार बदल सकते हैं (कहते हैं, यदि चरित्र के जन्म वर्ष का उपयोग पहले अनिवार्य था और फिर वैकल्पिक हो गया तो एपीआई बदल जाएगा)। हम एपीआई परिवर्तनों को ट्रैक कर सकते हैं और एपीआई डेवलपर्स को सही समय पर संकेत देकर चेतावनी दे सकते हैं कि, कुछ परिवर्तन करके, वे ग्राहकों के प्रदर्शन को बाधित कर सकते हैं।

परिणाम

अनुप्रयोग प्रोटोकॉल की एक पूरी श्रृंखला है जो कंप्यूटर एक दूसरे के साथ संवाद करने के लिए उपयोग कर सकते हैं।

इस स्पेक्ट्रम का एक पक्ष आरपीसी फ्रेमवर्क जैसे थ्रिफ्ट और जीआरपीसी द्वारा दर्शाया गया है। वे इसमें भिन्न हैं कि वे आम तौर पर अनुरोधों और प्रतिक्रियाओं के लिए सख्त प्रकार निर्धारित करते हैं और अनुरोधों के संचालन के आयोजन के लिए क्लाइंट और सर्वर कोड उत्पन्न करते हैं। वे HTTP के बिना भी कर सकते हैं और JSON के बिना भी।

दूसरी ओर, पायथन में लिखित वेब फ्रेमवर्क हैं जो अनुरोधों और प्रतिक्रियाओं के लिए स्पष्ट अनुबंध नहीं रखते हैं। हमारा दृष्टिकोण अधिक स्पष्ट रूप से संरचित रूपरेखाओं के लिए अवसर प्रदान करता है, लेकिन साथ ही आपको HTTP + JSON बंडल का उपयोग जारी रखने की अनुमति देता है और इस तथ्य में योगदान देता है कि आपको एप्लिकेशन कोड में कम से कम परिवर्तन करना है।

यह ध्यान रखना महत्वपूर्ण है कि यह विचार नया नहीं है। दृढ़ता से टाइप की गई भाषाओं में कई रूपरेखाएं लिखी गई हैं जो डेवलपर्स को हमारे द्वारा वर्णित सुविधाओं के साथ प्रदान करती हैं। अगर हम पायथन के बारे में बात करते हैं, तो यह है, उदाहरण के लिए, एपीसार्ट फ्रेमवर्क।

हमने HTTP API के लिए प्रकारों के उपयोग को सफलतापूर्वक कमीशन किया है। हम इस तथ्य के कारण हमारे संपूर्ण कोड आधार में एपीआई टाइप करने के लिए वर्णित दृष्टिकोण को लागू करने में सक्षम थे, यह मौजूदा प्रस्तुति कार्यों के लिए अच्छी तरह से लागू है। हमने जो भी किया उसका मूल्य हमारे सभी प्रोग्रामरों के लिए स्पष्ट है। अर्थात्, हम इस तथ्य के बारे में बात कर रहे हैं कि स्वचालित रूप से उत्पन्न प्रलेखन उन लोगों के लिए संचार का एक प्रभावी साधन बन गया है जो इंस्टाग्राम क्लाइंट लिखने वालों के साथ सर्वर के विकास में शामिल हैं।

प्रिय पाठकों! आप अपने पायथन प्रोजेक्ट्स में HTTP APIs के डिज़ाइन को कैसे अप्रोच करते हैं?