HTTP के हेडर के लिए कन्वेंशन, अपग्रेड किए गए एपीआई के ग्राहकों को सूचित करने के लिए

Question

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

Answer 1

मैं बैकवर्ड संगत होने के लिए स्थिति कोड में कुछ भी नहीं बदलूंगा। मैं प्रतिक्रिया में "चेतावनी" शीर्षक जोड़ूंगा:

Warning: 299 - "Deprecated API"

आप "एजेंट" के साथ "-" को भी निर्दिष्ट कर सकते हैं जो चेतावनी का उत्सर्जन करता है, और चेतावनी-पाठ में अधिक स्पष्ट है:

Warning: 299 api.blazingFrog.com "Deprecated API: use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"

चेतावनी हेडर यहां निर्दिष्ट किया गया है: https://tools.ietf.org/html/rfc7234#section-5.5 । वार्न-कोड 299 सामान्य है, "पदावनत" मानक नहीं है।

आपको अपने एपीआई क्लाइंट को HTTP चेतावनियों को लॉग इन करने और इसे मॉनिटर करने के लिए बताना होगा।

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

संपादित करें (2019-04-25): जैसा कि @ हैरी वुड ने उल्लेख किया है, चेतावनी हेडर प्रलेखन में कैशिंग से संबंधित अध्याय में है। हालाँकि, RFC स्पष्ट हैWarnings can be used for other purposes, both cache-related and otherwise.

यदि आप एक वैकल्पिक विधि पसंद करते हैं, तो यह ड्राफ्ट https://tools.ietf.org/html/draft-dalal-deprecation-header-00 एक नया हेडर "डिप्रेसेशन" सुझाता है।

Comments

चेतावनी-मूल्य के अंत में चेतावनी-तिथि यहां कोई उद्देश्य नहीं देती है, और इसे छोड़ना सबसे अच्छा है, या आप भ्रमित करने वाले ग्राहकों को जोखिम में डालते हैं: “यदि कोई प्राप्तकर्ता है। । । एक चेतावनी-तारीख प्राप्त करता है जो एक Dateही संदेश में मूल्य से अलग है , प्राप्तकर्ता को चेतावनी-मूल्य को बाहर करना होगा। । । इससे पहले । । । संदेश का उपयोग करते हुए। ”

— वासिलि फरोनोव

यदि आप वॉर्न-डेट को शामिल करते हैं, तो इसे Dateहेडर की तरह ही स्वरूपित किया जाना चाहिए "Thu, 02 Apr 2015 12:25:32 GMT":।

— वसीली फ़ारोनोव

@VasiliyFaronov: आप सही हैं, क्योंकि उस स्थिति में (अपग्रेड किया गया API) यह चेतावनी संदेश भविष्य में हमेशा सही रहेगा। इसलिए यदि प्रतिक्रिया (चेतावनी संदेश के साथ) एक प्रॉक्सी में कैश द्वारा भेजी जाती है और संदेश की तारीख अलग है, तो चेतावनी को नजरअंदाज कर दिया जाएगा जबकि यह अभी भी मान्य होगा। मैं प्रतिक्रिया को संपादित करता हूं

— BenC

हालांकि कैशिंग से संबंधित "चेतावनी" हेडर नहीं है? मेरा मतलब है कि आपके डॉक्यूमेंटेशन लिंक में कैशिंग का उल्लेख है, लेकिन यह भी कि पूरे RFC डॉक्यूमेंट से संबंधित कैचिंग लगती है। लेकिन Warningहैडर अपचयन का वर्णन करने के लिए मुक्त-पाठ स्थान के रूप में अच्छा दिखता है। Deprecationऔर Sunsetहेडर अन्य उत्तर में उल्लेख किया है, एक तंग अधिक संभावित मशीन पठनीय रास्ते में निंदा वर्णन करने के लिए एक उभरते मानक समाधान प्रतीत होता है।

— हैरी वुड

Warningहेडर केवल कैश से संबंधित नहीं है। Warningअनुभाग में पहला वाक्य "चेतावनी अन्य प्रयोजनों के लिए इस्तेमाल किया जा सकता है, दोनों कैश-संबंधी और अन्यथा।"

— .लेबी मूरत

Answer 2

आप 410 (चला गया) का उपयोग कर सकते हैं ।

यहां बताया गया है कि W3C की स्थिति कोड परिभाषाएं इसका वर्णन कैसे करती हैं:

410 (गया)

अनुरोधित संसाधन अब सर्वर पर उपलब्ध नहीं है और कोई अग्रेषण पता ज्ञात नहीं है। इस स्थिति को स्थायी माना जाता है। लिंक संपादन क्षमताओं वाले ग्राहक उपयोगकर्ता अनुमोदन के बाद अनुरोध-यूआरआई के संदर्भ हटा सकते हैं। यदि सर्वर को पता नहीं है, या यह निर्धारित करने के लिए कोई सुविधा नहीं है कि क्या स्थिति स्थायी है या नहीं, तो स्थिति कोड 404 (नहीं मिला) SHOULD का उपयोग किया जाना चाहिए। जब तक अन्यथा संकेत न दिया जाए, यह प्रतिक्रिया अस्वीकार्य है।

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

Comments

410 के साथ समस्या यह है कि यह "होने वाली पदावनत" आवश्यकता से मेल नहीं खाता ... जब एपीआई चला गया है यह ठीक काम करता है, लेकिन नहीं है कि यह है जाएगा में चला गया हो भविष्य ।

— जुलिएन जेनस्टौक्स

यदि आप 410 लौटाते हैं तो आप अपनी पिछड़ी अनुकूलता को तोड़ देंगे

— BenC

410 Goneयह पदावनति के बारे में नहीं है, यह विधि के बारे में बहुत अधिक उपलब्ध नहीं है। जैसा कि @BenC ने कहा, बेहतर तरीका यह है कि वार्निंग हैडर

— sempasha

यह

— अपग्रेड किए

Answer 3

मैं 301 (स्थायी रूप से स्थानांतरित) के साथ चला गया हूं । 300 श्रृंखला कोड क्लाइंट को यह बताने वाले हैं कि उनके पास एक कार्रवाई करने के लिए है।

Comments

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

— १०:२५

वास्तव में स्थानांतरित होने के लिए कोई स्थिति नहीं है। 302 (अनुरोधित संसाधन किसी अन्य स्थान पर अस्थायी रूप से रहता है, लेकिन यह अभी भी अनुरोधित यूआरआई पर पाया जा सकता है।) ...

— u07ch

मैं एक स्थिति की तलाश नहीं कर रहा हूं, लेकिन प्रतिक्रिया में जोड़ने के लिए "मानक" शीर्ष लेख के लिए।

— ब्लेजिंगफ्रॉग

इस तरह की प्रतिक्रिया के लिए कोई मानक शीर्ष लेख नहीं है। आपको अपना स्वयं का एक हेडर बनाना चाहिए और इसे अपने स्वयं के एपि के प्रलेखन में वर्णन करना चाहिए।

— ब्रायन केली

मुझे लगता है कि कोई भी प्रतिक्रिया कोड> = 300 चीजों को तोड़ने के लिए है। 299 ग्राहकों को अपने आवेदन को तब तक जीवित रखने की अनुमति देगा जब तक कि आवश्यक बदलाव न करते हुए एपीआई अक्षम हो।

— देवलोक

Answer 4

मैं एक 207 Multi-Statusप्रतिक्रिया की सिफारिश करता हूं , यह दर्शाता है कि यह एक सफल प्रतिक्रिया है, लेकिन इसमें संभावित रूप से दूसरा पदावनत स्थिति भी है।

Comments

दिलचस्प। मैं उस एक के बारे में नहीं जानता था, लेकिन मुझे लगता है कि व्यवहार में एक मजबूत खतरा है कि आप कुछ ग्राहकों के लिए एक अलग प्रतिक्रिया कोड को स्वैप करके परिवर्तन को पेश करेंगे, भले ही यह 200 की सीमा में हो। मुझे लगता है कि आप दबाव से कोमल चूहे मारने का काम कर सकते हैं। Deprecationहेडर के साथ शुरू करें (जो ग्राहकों को दुर्भाग्य से अनदेखा करने की संभावना है) फिर बाद में इस 207 कोड का उपयोग करें, फिर बाद में 301 चले गए, फिर अंत में 410 चले गए!

— हैरी वुड

Answer 5

@ Dret की प्रतिक्रिया को परिष्कृत करना। पदावनति के लिए दो प्रासंगिक HTTP हेडर हैं: Deprecation( https://tools.ietf.org/html/draft-dalal-deprecation-header-00 ) और Sunset।

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

हटाए गए संसाधन की नियोजित सूर्यास्त तिथि के बारे में उपयोगकर्ताओं को सूचित करने के लिए, Sunsetहैडर का उपयोग डिप्रेसेशन हेडर के अतिरिक्त किया जाना चाहिए। यह खंड # 5 https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5 में वर्णित है ।

हैडर का # 11 ड्राफ्ट https://tools.ietf.org/html/draft-wilde-sunset-header-11Sunset इस पहलू को स्पष्ट करता है और साथ ही सेक्शन 1.4 https://tools.ietf.org/html/draft-wilde -सुनसेट-हेडर -11 # सेक्शन-1.4 ।

Answer 6

एक HTTP हैडर फ़ील्ड है, जिसे Sunsetकिसी संसाधन के आगामी अपचयन का संकेत देने के लिए कहा जाता है। https://tools.ietf.org/html/draft-wilde-sunset-header आरएफसी बनने के अंतिम चरण में है। आदर्श रूप से, आपके एपीआई को यह दस्तावेज़ करना चाहिए कि यह उपयोग करने जा रहा है Sunset, ताकि ग्राहक इसे देख सकें और उस पर कार्य कर सकें, यदि वे चाहते हैं।