💻 👧🏻 ⛸️ वेब एपीआई विकास 🔟 😳 😡

परिचय

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

अनुवादक की टिप्पणी पाठ में आती है, वे इटैलिक में हैं ।

हम एपीआई इकट्ठा करते हैं जो अन्य डेवलपर्स पसंद करेंगे

एपीआई कॉल के लिए अनुकूल URL

अच्छे REST डिजाइन का पहला सिद्धांत चीजों को स्पष्ट और सरल बनाना है । आपको अपने API कॉल के लिए मूल URL से शुरू करना चाहिए।

आपके कॉल पते बिना दस्तावेज के भी स्पष्ट होने चाहिए। ऐसा करने के लिए, लघु और स्पष्ट आधार URL का उपयोग करके किसी भी इकाई का वर्णन करने के लिए एक नियम बनाएं जिसमें अधिकतम 2 पैरामीटर हों । यहाँ एक महान उदाहरण है:

/dogs
/dogs/12345

संज्ञाएं अच्छी हैं, और क्रियाएं खराब हैं

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

/getAllDogs
/getAllLeashedDogs
/getDog
/newDog
/saveDog

इन चुनौतियों को देखें? यह भयावह है।

क्रियाओं के बजाय - एचटीटीपी

हमने सिर्फ दो आधार संज्ञा URL का उपयोग करके कुत्तों का वर्णन किया है। अब हमें बनाई गई संस्थाओं के साथ काम करने की जरूरत है। सबसे अधिक बार, पढ़ने, बनाने, संपादित करने और हटाने के संचालन की आवश्यकता होती है (CRUD - बनाएँ - पढ़ें - अपडेट - हटाएं)। इसके लिए, HTTP तरीके GET , POST , PUT, और DELETE हमारे लिए एकदम सही हैं।

POST /dogs —
GET /dogs —
PUT /dogs —
DELETE /dogs —

POST /dogs/12345 — ( 12345 )
GET /dogs/12345 —
PUT /dogs/12345 — 12345
DELETE /dogs/12345 —

बेस यूआरएल सरल दिखते हैं, क्रियाओं का उपयोग नहीं किया जाता है, सब कुछ सहज और स्पष्ट है। ब्यूटी!

बहुवचन

आधार URL का वर्णन करने के लिए बहुवचन संज्ञाओं का उपयोग करना अच्छा है। इससे भी बदतर - एकवचन में। एकवचन और बहुवचन में संज्ञाओं के साथ पतों को मिलाना बुरा है।

/checkins Foursquare
/deals y GroupOn
/Product y Zappos

ठोस नाम अमूर्त से बेहतर हैं

सार नाम - इसे अक्सर एपीआई आर्किटेक्ट द्वारा शांत माना जाता है। और यह उन लोगों के लिए बिल्कुल अच्छा नहीं है जो बाद में इस एपीआई के साथ काम करेंगे।
/ ब्लॉग, वीडियो / समाचार, / लेख - यह स्पष्ट लगता है। लेकिन / आइटम और / संपत्ति नहीं हैं।

संचार

कुछ संसाधन हमेशा अन्य संसाधनों से जुड़े होते हैं। क्या एपीआई के माध्यम से इन रिश्तों को दिखाने का एक स्पष्ट और आसान तरीका है? इसके अलावा, संज्ञा और क्रिया में हमारे विभाजन को याद रखना?

GET /owners/5678/dogs
POST /owners/5678/dogs

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

साइन के पीछे जटिल चीजों को छिपाने की जरूरत है "?"

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

GET /dogs?color=red&state=running&location=park

गलतियों के बारे में क्या?

एक अच्छी त्रुटि हैंडलिंग तंत्र किसी भी अच्छे एपीआई का हिस्सा है। आइए देखें कि लोकप्रिय एपीआई में त्रुटियां क्या दिखती हैं।

फेसबुक
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803) Some of the aliases you requested do not exist: foo.bar"}

इससे कोई फर्क नहीं पड़ता कि अनुरोध कैसे निष्पादित किया जाता है - फेसबुक हमेशा हमें 200 ओके कोड वापस कर देगा।

Twilio
HTTP Status Code: 401
{"status" : "401", "message":"Authenticate","code": 20003, "more info": "http://www.twilio.com/docs/errors/20003"}

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

SimpleGeo
HTTP Status Code: 401
{"code" : 401, "message": "Authentication Required"}

SimpleGeo HTTP कोड में एक त्रुटि संदेश देता है और प्रतिक्रिया के शरीर में इसे थोड़ा स्पष्टीकरण प्रदान करता है।

HTTP प्रतिक्रिया कोड का उपयोग करें

HTTP प्रतिक्रिया कोड लेने के लिए स्वतंत्र महसूस करें और अपने एपीआई की प्रतिक्रियाओं के साथ सहसंबंधित करें। कुल मिलाकर, लगभग 70 कोड लगातार उपयोग में हैं। कुछ डेवलपर्स इन सभी को याद करते हैं, इसलिए 70 में से लगभग 10 को लेना बेहतर है। वैसे, अधिकांश एपीआई प्रदाता ऐसा करते हैं।

Google gdata
200 201 304 400 401 403 404 409 410 500

नेटफ्लिक्स
200 201 304 400 401 403 404 412 500

डिग
200 400 401 403 404 410 500 503

HTTP त्रुटि कोड क्या उपयोग करने लायक हैं?

केवल 3 एपीआई प्रतिक्रियाएं संभव हैं

अनुरोध सफल रहा
गलत डेटा इनपुट - क्लाइंट त्रुटि पर भेजा गया था
डेटा संसाधित करते समय एक त्रुटि हुई - सर्वर त्रुटि

तो आप आधार के रूप में 3 प्रतिक्रिया कोड ले सकते हैं:

200 ठीक है
400 बुरा अनुरोध
500 आंतरिक सर्वर त्रुटि

यदि आपके लिए 3 कोड पर्याप्त नहीं हैं - तो दूसरा 5 लें:

201 बनाया गया (रिकॉर्ड बनाया गया)
304 संशोधित नहीं (डेटा नहीं बदला गया है)
404 नहीं मिला
401 अनधिकृत
403 निषिद्ध (प्रवेश निषेध)

आँख बंद करके इस अभ्यास का पालन नहीं करना सबसे अच्छा है। HTTP प्रतिक्रिया कोड का उपयोग करने के लाभों को मापें
प्रत्येक मामले में। सबसे अधिक संभावना है, प्रतिक्रिया कोड का उपयोग हमेशा उचित और उचित नहीं होगा। उदाहरण के लिए, यदि आप एक छोटे से वेब अनुप्रयोग के लिए एक बैकएंड लिख रहे हैं, तो आप आसानी से प्रतिक्रिया शरीर में त्रुटि कोड तक खुद को सीमित कर सकते हैं। और मानक 200 ओके प्रतिक्रिया आपको दो त्रुटि हैंडलिंग तंत्र बनाने की अनुमति देगा: सर्वर त्रुटियों के लिए और स्वयं एपीआई की त्रुटियों के लिए। सामान्य तौर पर - सोचें, तौलना। और फिर एक निर्णय लें।

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

किसी संस्करण को निर्दिष्ट किए बिना कभी भी एक एपीआई जारी न करें

ट्विलियो /2010-04-01/Accounts
salesforce.com /services/data/v20.0/sobjects/Account
फेसबुक ?v=1.0

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

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

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

एपीआई में संस्करणों को कैसे लागू किया जाए?

V उपसर्ग, पूर्णांक का उपयोग करें, और पता के बाईं ओर संस्करण संख्या रखें। उदाहरण के लिए, / v1 / कुत्ते ।
कम से कम एक पिछला संस्करण काम करते रहें

आप सर्वर प्रतिसाद शीर्ष लेख में संस्करण भी निर्दिष्ट कर सकते हैं। एपीआई के साथ काम करने पर यह कुछ अतिरिक्त सुविधाएँ प्रदान कर सकता है। लेकिन अगर आप कई अलग-अलग संस्करणों का उपयोग करते हैं और आपको शीर्षकों में उन्हें इंगित करने की आवश्यकता होती है - यह एक बड़ी समस्या का एक लक्षण है।

आंशिक उत्तर

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

लिंक्डिन /people: (id, first-name, last-name, industry)
Facebook /joe.smith/friends?fields=id,name,picture
Google ?fields=title, media:group(media:thumbnail)

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

सिंपल पेजिंग करें

पहले अनुरोध पर सभी रिकॉर्ड देना एक बहुत बुरा विचार है। इसलिए, आपको निश्चित रूप से पेजिंग के लिए प्रदान करना चाहिए। आइए देखें कि लोकप्रिय एपीआई में आप 50 से 75 तक रिकॉर्ड कैसे खींच सकते हैं।

फेसबुक: 50 25
ट्विटर: 3 25
लिंक्डिन: 50- 25

हम सीमा और ऑफसेट का उपयोग करने की सलाह देते हैं। यह दृष्टिकोण अधिक सहज है।

/dogs?limit=25&offset=50

यह प्रत्येक उत्तर के लिए मेटा-जानकारी को जोड़ने के लायक है: वर्तमान पृष्ठ, कितने रिकॉर्ड उपलब्ध हैं।

डिफ़ॉल्ट मान प्रदान करें: यदि उपयोगकर्ता ने अनुरोध में पेजेशन मापदंडों को पारित नहीं किया है, तो सीमा को 10 और ऑफसेट को 0 मानें (पहले 10 प्रविष्टियों को प्रिंट करें)।

कार्रवाई के बारे में क्या?

सभी API ऐसे रिकॉर्ड नहीं हैं जिन्हें पढ़ा, संपादित और हटाया जा सकता है। एपीआई एक्शन भी हैं। अनुवाद, गणना, रूपांतरण सभी क्रियाएं हैं।

ऐसे प्रश्नों के लिए संज्ञा के बजाय क्रिया का उपयोग करना सबसे अच्छा है।

/convert?from=EUR&to=USD&amount=100

सुनिश्चित करें कि यहां तक कि प्रलेखन में कॉल सूची को देखने से भी संस्थाओं को कार्यों से अलग किया जा सकता है।

कई प्रारूपों के लिए समर्थन

कई प्रतिक्रिया प्रारूपों का समर्थन करना बहुत अच्छा है।

Google ?alt=json
Foursquare /venue.json
Digg ?type=json

वैसे, डिग आप HTTP HTTP हेडर के माध्यम से प्रतिक्रिया प्रारूप सेट करने की अनुमति देता है।

हम Foursquare दृष्टिकोण की सलाह देते हैं।

/dogs.json
/dogs/1234.json

आप न केवल विभिन्न स्वरूपों में एपीआई प्रतिक्रियाएं प्रदान कर सकते हैं, बल्कि विभिन्न प्रकार के ग्राहकों के लिए भी जवाब दे सकते हैं। उदाहरण के लिए, आप एक एपीआई बना सकते हैं जो एक iOS एप्लिकेशन और एक वेब एप्लिकेशन के सामने के छोर के साथ एक साथ काम कर सकता है। यह इस तरह दिख सकता है: /dogs.ios और /dogs.web।

डिफ़ॉल्ट प्रारूप

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

नाम बताएं

गुण कई तरह से कहे जा सकते हैं।

Twitter ने created_at
बिंग DateTime
Foursquare createdAt

नामकरण चर के लिए कई सम्मेलन हैं। रूबी ऑन रेल विशेषज्ञों के रूप में, ट्विटर सम्मेलन हमारे करीब है। लेकिन हम फोरस्क्वेयर दृष्टिकोण को सबसे अच्छा तरीका मानते हैं: - कैमलकेस (एक छोटे अक्षर के साथ चर, कक्षाएं - एक पूंजी के साथ)। यह नामकरण सम्मेलन JSON को डेटा सबमिट करने के लिए सबसे बेहतर है: डेटा जावास्क्रिप्ट की तरह दिखता है। जो, सामान्य रूप से, JSON के लिए तार्किक है।

यद्यपि लेखक अधिक बार कैमकेलेज का उपयोग करने की सलाह देता है, ग्राहक के बारे में सोचना और फिर निर्णय लेना बेहतर है। उदाहरण के लिए, C में लिखा गया एक प्रोग्राम आपके API के साथ संवाद कर सकता है, और उसके लिए कुछ_उपाय_का उपयोग करना बेहतर है ।

खोज

वैश्विक खोज सरल है:

/search?q=search+word

विशिष्ट संस्थाओं के लिए एक खोज की कल्पना आसानी से की जा सकती है जो हमने पहले सीखा था:

/owners/5678/dogs?q=red

और विभिन्न स्वरूपों में डेटा प्रस्तुत करने के लिए, हम एक्सटेंशन को याद करते हैं:

/search.xml?q=search+word

एक डोमेन पर सभी एपीआई कॉल लीजिए

फेसबुक दो डोमेन प्रदान करता है।

api.facebook.com यह पता पहली बार दिखाई दिया
graph.facebook.com इस पते को वैश्विक ग्राफ के कार्यान्वयन के बाद दर्ज किया गया था

फोरस्क्वेयर एक पते तक सीमित है

api.foursquare.com

ट्विटर को 3 पते मिले, जिनमें से 2 पोस्ट और खोज पर केंद्रित हैं

stream.twitter.com
api.twitter.com
search.twitter.com

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

बस मामले में, मैं आपको याद दिलाता हूं कि वेब एप्लिकेशन के लिए एक छोटे बैकएंड के डेवलपर्स को एक अलग डोमेन आवंटित करने की आवश्यकता नहीं है, ताकि सामने के छोर पर क्रॉस-डोमेन अजाक्स अनुरोधों के साथ समस्याएं पैदा न करें।

रीडायरेक्ट के

यदि कोई आपके API डोमेन तक पहुँच प्राप्त करता है और किसी भी पैरामीटर को पास नहीं करता है, तो डेवलपर्स के लिए प्रलेखन के साथ डोमेन पर पुनर्निर्देशित करने के लिए स्वतंत्र महसूस करें। कुछ सहज ज्ञान युक्त प्रलेखन डोमेन प्राप्त करें और मुख्य डेवलपर डोमेन पर पुनर्निर्देशित करें।

api.* -> developers.*
dev.* -> developers.*
developer.* -> developers.*

HTTP प्रतिक्रिया कोड और क्लाइंट अपवाद

जैसा कि हमने पहले कहा था, केवल एपीआई प्रतिक्रिया के शरीर में ही नहीं, बल्कि HTTP प्रतिक्रिया कोड में भी त्रुटि कोड भेजना सबसे अच्छा है। लेकिन क्या होगा यदि क्लाइंट 200 से अलग कोई भी HTTP कोड प्राप्त करते समय एक अपवाद फेंकता है? ऐसे मामलों के लिए, ट्विटर के लोगों ने अनुरोध करने के लिए एक पैरामीटर जोड़ने के लिए एक शानदार और सरल समाधान प्रदान किया।

/public_timelines.json?suppress_response_code=true

नतीजतन, त्रुटियां कोड 200 के साथ आएंगी।
अपने API में suppress_response_codes पैरामीटर प्रदान करें और इसे डिफ़ॉल्ट रूप से सही पर सेट करें।

लेकिन क्या होगा अगर क्लाइंट HTTP तरीकों के सीमित सेट का समर्थन करता है?

इस स्थिति में, आपको GET मापदंडों का उपयोग करके एक पूर्ण REST API का अनुकरण करने की आवश्यकता है।

/dogs
/dogs?method=post
/dogs/1234?method=put
/dogs/1234?method=delete

इस दृष्टिकोण से सावधान रहें! यदि आप गलत तरीके से इस तरह के लिंक को संभालते हैं और उन्हें उचित सुरक्षा प्रदान नहीं करते हैं, तो बॉट्स (जैसे Google खोज रोबोट) इन लिंक को ट्रिगर कर सकते हैं। और आप हर बार बॉट में प्रवेश करने पर असीम रूप से बनाए गए और हटाए गए रिकॉर्ड प्राप्त करेंगे।

प्राधिकरण

यह एक जटिल मुद्दा है, और मेरे सहकर्मी और मैं कभी भी जल्दी सहमत नहीं हो सकते। आइए देखें कि अग्रणी खिलाड़ी क्या करते हैं।

पेपैल अनुमतियाँ सेवा एपीआई
फेसबुक OAuth 2.0
ट्विटर 1.0a

कृपया ध्यान दें कि OAuth का आविष्कार होने से पहले ही PayPal ने अपनी प्राधिकरण प्रणाली लागू कर दी थी।

यदि आपको तृतीय-पक्ष एप्लिकेशन के माध्यम से उपयोगकर्ता प्राधिकरण की आवश्यकता है - केवल OAuth। और किसी भी तरह से OAuth की तरह कुछ नहीं करते हैं, लेकिन "थोड़ा अलग है।"

चट्टी एपीआई

"चैटी" - इसका मतलब है कि लोकप्रिय ऑपरेशन करने के लिए आपको एक पंक्ति में 3-4 एपीआई कॉल करना होगा। यह बुरा है।

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

वेब एपीआई विकास