एपीआई निर्माण

कुछ हफ़्ते पहले, हमने सार्वजनिक रूप से Gauges API जारी किया था। पहले से मौजूद Gauges के बावजूद, एपीआई लिखते समय काफी काम था। विस्तार से विवरण से निपटने के लिए आवश्यक है।

1. एपीआई निर्माण के दौरान दस्तावेज लिखें

एपीआई लगभग तैयार होने के बाद हमने दस्तावेज तैयार करने में गलती की। समस्या यह है कि प्रलेखन बेकार है। बाद में इस दिनचर्या को छोड़कर, जब आप एपीआई जारी करने में प्रसन्न होंगे, तो काम दोगुना मुश्किल हो जाएगा। सौभाग्य से, हमारे पास वे थे जो इससे पहले गए थे।

2. स्थिर रहें

हमारे एपीआई दस्तावेज लिखते समय, हमने कई असंगत बिंदुओं पर ध्यान दिया। उदाहरण के लिए, कुछ स्थानों पर हमने हैश लौटाया, और अन्य में - एक सरणी। समस्या को समझते हुए, हमने कुछ नियम बनाने शुरू किए।

सरणी / हैश समस्या को हल करने के लिए, हमने हमेशा उत्तर के रूप में हैश वापस करने का विकल्प चुना। यह सबसे लचीला समाधान है, हमारे भविष्य के कार्यों पर ध्यान केंद्रित करना। हम अपनी सेवा से प्रतिक्रिया को बदलने या एपीआई के एक नए संस्करण को जारी करने की आवश्यकता के बिना, नई चाबियाँ शुरू करने में सक्षम थे।

हैश के साथ सरणियों को बदलने का मतलब है कि हमें चाबियों के साथ सरणियों के लिए एक नामस्थान की आवश्यकता है। इसके अलावा, हमने देखा कि हर चीज का अपना नाम स्थान नहीं था। और फिर, हम एक नियम लेकर आए। इस स्थिति में, सभी शीर्ष-स्तरीय ऑब्जेक्ट में एक नामस्थान होना चाहिए, लेकिन इन ऑब्जेक्ट्स या कई ऑब्जेक्ट्स के सेट के बच्चों के लिए नामस्थान आवश्यक नहीं हैं।

{users:[{user:{...}}, {user:{...}}]} //  {users:[{...}, {...}]} //  {username: 'jnunemaker'} //  {user: {username:'jnunemaker'}} //  

खैर, आपको बात समझ में आ गई। संगति जरूरी है। एक प्रारूप का हमेशा पालन किया जाना चाहिए।

3. URL प्रदान करें

मेरे अधिकांश ओपन सोर्स काम विभिन्न एपीआई लपेटते रहे हैं। और एक बात ने मुझे बहुत परेशान किया, यह उरोज पैदा कर रहा था। प्रत्येक संसाधन को उन URL को जानना चाहिए जो इसके लिए महत्वपूर्ण हैं। उदाहरण के लिए, Gauges के उपयोगकर्ताओं के पास कई URL हैं जिन्हें कुछ डेटा पुनर्प्राप्त करने के लिए कहा जा सकता है:

 { "user": { "name": "John Doe", "urls": { "self": "https://secure.gaug.es/me", "gauges": "https://secure.gaug.es/gauges", "clients": "https://secure.gaug.es/clients" }, "id": "4e206261e5947c1d38000001", "last_name": "Doe", "email": "john@doe.com", "first_name": "John" } } 

पिछला JSON / me संसाधन से एक प्रतिक्रिया है। यह प्रमाणित उपयोगकर्ता के बारे में और साथ ही स्वयं (स्वयं) को अपडेट करने के लिए URL, सभी आँकड़े (/ गेज) प्राप्त करता है, और सभी API क्लाइंट (/ क्लाइंट) प्राप्त करता है। मान लीजिए आपका अगला अनुरोध / गेज है। प्रत्येक गेज (आँकड़े) अधिक जानकारी के लिए कुछ और पते लौटाता है।

 { "gauges": [ { // various attributes "urls": { "self":"https://secure.gaug.es/gauges/4ea97a8be5947ccda1000001", "referrers":"https://secure.gaug.es/gauges/4ea97a8be5947ccda1000001/referrers", "technology":"https://secure.gaug.es/gauges/4ea97a8be5947ccda1000001/technology", // ... etc }, } ] } 

हमें लगता है कि यह इसके लायक साबित होगा। और हम भविष्य में देखेंगे कि क्या यह अच्छा काम करेगा।

4. रिपोर्टिंग

और अंत में, नियंत्रक से या प्राप्त / पोस्ट / sinatra ब्लॉक से to_json और उसके दोस्तों का उपयोग कभी न करें। आपके द्वारा to_json को कॉल करना शुरू करने के बाद: विधियों,: के अलावा,: केवल, या अन्य विकल्पों के साथ, आप यह सब एक अलग वर्ग में ले जाना चाह सकते हैं।

Gauges के लिए, हम इन वर्गों को प्रस्तुतकर्ता कहते हैं। उदाहरण के लिए, यहाँ UserPresenter का सरलीकृत संस्करण है।

 class UserPresenter def initialize(user) @user = user end def as_json(*) { 'id' => @user.id, 'email' => @user.email, 'name' => @user.name, 'first_name' => @user.first_name, 'last_name' => @user.last_name, 'urls' => { 'self' => "#{Gauges.api_url}/me", 'gauges' => "#{Gauges.api_url}/gauges", 'clients' => "#{Gauges.api_url}/clients", } } end end 

चिंता की कोई बात नहीं। ऐप / प्रेजेंटर्स पर स्थित एक साधारण हैक क्लास। यहाँ एक उदाहरण है कि हमारे सिनात्रा ऐप में मार्ग कैसे / मेरे लिए दिखता है।

 get('/me') do content_type(:json) sign_in_required {:user => UserPresenter.new(current_user)}.to_json end 

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

मुझे यकीन है कि उपरोक्त में से कोई भी चौंकाने वाला या अति-प्रेरणादायक नहीं था, लेकिन मुझे उम्मीद है कि लेख आपके अगले सार्वजनिक एपीआई के लिए कुछ समय बचाएगा।