डेटा बदलने वाले GET endpoint को write मंजूरी क्यों चाहिए?

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

टीमें अक्सर किसी अजीब घटना के बाद ऐसे रूट खोजती हैं और फिर परेशानी देने वाले एक endpoint को पैच कर देती हैं। यह बहुत सीमित उपाय है। आपको हर उस read-जैसी कॉल को खोजना होगा जो कुछ बदलती है, उसके असर को परिणाम के हिसाब से वर्गीकृत करना होगा और उसे साफ write जैसी authorization और audit सीमा के पीछे रखना होगा। verb बदलना जरूरी है, पर सुधार का केवल एक हिस्सा है।

सुरक्षित HTTP मेथड अनुरोध के अर्थ बताते हैं

डेटा बदलने वाले GET endpoint, मेथड के पीछे किए गए वादे का उल्लंघन करते हैं, भले ही उनके लेखक के पास GET चुनने की व्यावहारिक वजह रही हो। RFC 9110, GET को सुरक्षित मेथड कहता है और समझाता है कि सुरक्षित अनुरोध सर्वर से स्टेट बदलने को नहीं कहता। RFC, logging और accounting जैसे संयोगवश असर की अनुमति देता है, क्योंकि क्लाइंट ने वे असर नहीं माँगे थे। यह ऐसे रूट को छूट नहीं देता जिसका मकसद ही बदलाव करना हो।

यह अंतर एक आम बहाने को पकड़ता है: «आइटम पढ़ते समय सर्वर को last_seen अपडेट करना ही पड़ता है।» अगर क्लाइंट ने आइटम पाने को कहा और सेवा ने अंदरूनी access timestamp अपडेट किया, तो वह संयोगवश असर हो सकता है। अगर क्लाइंट ने आइटम पाने को कहा और सेवा ने invoice को paid चिह्नित कर दिया, export बना दिया, token खर्च कर दिया या workflow आगे बढ़ा दिया, तो बदलाव ही माँगा गया काम है। इसे write कहें।

RFC 9110 यह चिंता करने की परिचालन वजह भी देता है। user agent सुरक्षित मेथड को स्वचालित कर सकते हैं। कोई ब्राउज़र प्रीव्यू बनाने के लिए पेज ला सकता है। कोई crawler लिंक खोल सकता है। जवाब खोने पर client library दोबारा कोशिश कर सकती है। प्रोटोकॉल का अर्थ इन पक्षों को इस तरह काम करने की अनुमति देता है। आपका सर्वर इस पर निर्भर नहीं रह सकता कि हर कॉलर ने उसका बिना दस्तावेज़ वाला अपवाद पढ़ा होगा।

safe को idempotent से न मिलाएँ। DELETE idempotent हो सकता है, क्योंकि उसे दोहराने पर रिसोर्स हटाया ही रहता है, फिर भी वह unsafe है क्योंकि पहली कॉल स्टेट बदलती है। कोई GET जो हर अनुरोध पर counter बढ़ाता है, बहुत संकीर्ण अर्थ में idempotent हो सकता है अगर वह सीमा के बाद रुक जाए, फिर भी वह unsafe है क्योंकि उसका उद्देश्य स्टेट बदलना है। ये शब्द अलग सवालों का जवाब देते हैं:

• Safe पूछता है कि क्या कॉलर ने स्टेट बदलने को कहा।
• Idempotent पूछता है कि वही अनुरोध दोहराने पर अपेक्षित असर वही रहता है या नहीं।
• Cacheable पूछता है कि कोई intermediary जवाब दोबारा इस्तेमाल कर सकता है या नहीं।

जब टीम इन शब्दों को मिला देती है, तो अक्सर retry protection लगा कर मान लेती है कि समस्या हल हो गई। डुप्लिकेट रोकना मददगार है। यह किसी link scanner को पहली विनाशकारी कार्रवाई करने से नहीं रोकता।

संदिग्ध रूट नाम नहीं, परिणाम खोजें

छिपे बदलाव खोजने के लिए यह देखें कि रूट क्या करवाता है, उसके नाम या verb पर भरोसा न करें। getReport और view नाम के रूट काम को queue में डाल सकते हैं। reset नाम के रूट पूरी तरह बेनुकसान हो सकते हैं, अगर वे form लौटाते हों। अपना inventory runtime evidence और code path, दोनों से बनाएँ।

GET और HEAD के लिए registered हर handler से शुरुआत करें। हर handler में सीधे write और आगे भेजे जाने वाले काम trace करें: database transaction, queue publishing, business meaning वाला cache invalidation, email या chat delivery, payment, credential बदलाव, file deletion और दूसरी service को जाने वाली calls। internal service को कॉल करने वाला GET handler अपने repository में साफ दिख सकता है, जबकि वही internal call बदलाव करती हो। तब तक उसे follow करें, जब तक अंतिम असर का नाम न बता सकें।

यह साधारण खोज बहुत पुराना code पकड़ लेती है:

rg -n 'GET|\.get\(|router\.get\(|app\.get\(' src
rg -n 'INSERT|UPDATE|DELETE|enqueue|publish|sendMail|charge|revoke|rotate' src

आउटपुट का रूप, उससे बनने वाले review record जितना उपयोगी नहीं है। हर निष्कर्ष में endpoint, trigger, अंतिम असर, प्रभावित system और callers की सूची रखें। असर वाले कॉलम में «status अपडेट करता है» न लिखें। लिखें: «deployment d-481 को cancelled चिह्नित करता है और cancellation scheduler को भेजता है।» अस्पष्ट entries, reviewer को गंभीर कार्रवाई को आसानी से आगे बढ़ाने देती हैं।

runtime data वह खोजता है जो source review से छूट जाता है। non-production environment में correlation ID के साथ representative अनुरोध भेजें। फिर उस ID के लिए application logs, job tables, outbound-call logs और audit records खोजें। अगर GET अनुरोध से message, row change, queue item या external request बनता है, तो पूरी chain दर्ज करें। कोई रूट कई सेकंड बाद scheduled worker के जरिए बदलाव कर सकता है, इसलिए केवल request log भ्रामक हो सकता है।

ऐसे बदलावों पर नज़र रखें जिन्हें developer इसलिए खारिज कर देते हैं कि वे relational database write नहीं हैं। single-use download URL बनाना capability खर्च करता है। export शुरू होने से बड़ा bill बन सकता है। «invite acceptance» रूट पढ़ने से कोई user organization में जुड़ सकता है। report endpoint कॉल करने से महँगा warehouse job शुरू हो सकता है। लौटाया गया resource read-only हो सकता है, पर उसे बनाने वाली कार्रवाई नहीं।

पुराने API परिचित जगहों में write छिपाते हैं

सबसे खराब legacy route अक्सर human-facing page के shortcut के रूप में शुरू हुए थे। किसी ने administrative link को क्लिक करना आसान बनाया, फिर किसी दूसरी service ने URL कॉपी कर लिया, फिर कोई script उस पर निर्भर हो गई और shortcut API contract बन गया।

password-reset confirmation link इसका जाना-पहचाना उदाहरण हैं। GET /reset/confirm?token=... जैसा रूट सुविधाजनक दिखता है क्योंकि ब्राउज़र इसे खोल सकता है। अगर URL खोलने से token खर्च होता है और password बदलता है, तो mail scanner और preview tool पहले ही उसे खर्च कर सकते हैं। सुरक्षित डिज़ाइन में GET कुछ खर्च किए बिना confirmation state दिखाता है, फिर POST confirmation submit करता है। पेज में थोड़े समय के लिए मान्य server-side reference हो सकता है, लेकिन write केवल साफ कार्रवाई के बाद होती है।

unsubscribe link को कम नहीं, ज्यादा सावधानी चाहिए। email system और privacy law one-click unsubscribe को आकर्षक बनाते हैं और कुछ standard इसकी अपेक्षा करते हैं। अगर mailbox security scanner ऐसे लिंक का पीछा करे, तो recipient संदेश छुए बिना subscription खो सकता है। जहाँ लागू हो वहाँ standard header mechanism अपनाएँ, receiving ecosystem इसे कैसे संभालता है समझें और endpoint का व्यवहार जानबूझकर तय करें। किसी असंबंधित administrative API में सामान्य «GET unsubscribe» pattern कॉपी करके उसे precedent न कहें।

बार-बार दिखने वाले दूसरे उदाहरण:

• GET /jobs/123/retry, जो dashboard के हर refresh पर नया execution बनाता है।
• GET /deployments/123/rollback, जिसे monitoring probe लिंक जाँचते समय कॉल कर सकता है।
• GET /tokens/123/revoke, जो support URL को विनाशकारी capability बना देता है।
• GET /invoices/123/send, जो preview bot को mail sender में बदल देता है।
• GET /reports/monthly, जो report लौटाने के बजाय चुपचाप महँगा export शुरू कर देता है।

लोकप्रिय सलाह «बस secret query parameter जरूरी कर दें» गलत है। query string ब्राउज़र history, analytics, server logs, कुछ flow में referrer header, screenshot और copied message में फैल जाती हैं। और अहम बात यह है कि secret URL भी GET URL है। जिसे भी यह मिले, वह approval boundary के बिना कार्रवाई चला सकता है।

रीट्राई और प्रीव्यू नुकसान का दायरा बढ़ाते हैं

एक mutating GET के लेखक जितने कॉलर सोचते हैं, उससे कहीं ज्यादा स्वचालित कॉलर उसे दोहराने योग्य मानते हैं। पहला लक्षण अक्सर बेतरतीब लगता है: कोई operation दो बार होता है, कोई account रातोंरात बदल जाता है या user को ऐसी कार्रवाई दिखती है जो उसने नहीं की। request log में वैध credentials दिखते हैं, इसलिए घटना को operator error कह दिया जाता है। यह नाम अक्सर जाँच बहुत जल्दी रोक देता है।

एक legacy endpoint पर विचार करें जो GET /builds/77/retry मिलने पर remote build फिर से शुरू करता है। server के अनुरोध स्वीकार करने के बाद agent उसे ऐसे network path से लाता है जिसमें timeout हो जाता है। agent वही करता है जो बहुत से HTTP client करते हैं और retry करता है। मूल अनुरोध build 311 को पहले ही queue में डाल चुका है, दूसरा build 312 को डाल देता है। फिर dashboard activity feed में preview link लोड करता है और build 313 queue में डाल देता है। handler हर बार 200 OK लौटा सकता है, इसलिए जवाब में कुछ नहीं बताता कि operation duplicate हो गया।

redirect एक और चौंकाने वाली बात जोड़ सकता है। अगर पुरानी GET action नए रूट पर redirect करती है और नया रूट भी GET पर काम करता है, तो redirect असुरक्षित अर्थ को बनाए रखता है। अगर redirect मेथड को ऐसे बदल दे जिसकी client को उम्मीद न हो, तो client अलग-अलग तरह से fail हो सकते हैं। redirect migration में सहायक हैं, authorization या method semantics का बदलाव छिपाने की जगह नहीं।

cache इस failure को और अजीब बनाते हैं। shared cache को स्पष्ट निर्देश के बिना mutating GET का response store नहीं करना चाहिए, लेकिन system गलतियाँ करते हैं और developer यांत्रिक ढंग से cache header जोड़ देते हैं। cache storage न होने पर भी कोई prefetcher user के कार्रवाई तय करने से पहले अनुरोध भेज सकता है। सुरक्षा इस उम्मीद पर न बनाएँ कि हर intermediary आपके निजी इरादे का सम्मान करेगा।

सुधार सीमा से शुरू होता है। remote system बदल सकने वाले operation के लिए HTTP client के भेजने से पहले स्पष्ट action request चाहिए। caller को अलग action name, target और consequence दिखना चाहिए। भेजने के बाद timeout तब अनिश्चित write है, जिसे caller blind replay के बजाय status lookup या idempotency key से संभालता है।

कार्रवाई को write-जैसा contract दें

सुधारे गए endpoint को बदलाव अपने URI, method, request body, response और documentation में दिखाना चाहिए। इसे ठीक करने के लिए आपको noun-heavy REST बहस की जरूरत नहीं। ऐसा contract चाहिए जो कॉलर को action को fetch समझने से रोके।

build उदाहरण में POST action endpoint इस्तेमाल करें और idempotency key स्वीकार करें। endpoint को सामान्य success message के बजाय नए execution की पहचान करने वाला resource लौटाना चाहिए।

POST /v1/builds/77/retries HTTP/1.1
Idempotency-Key: 9ef8b462-97bf-4ca3-bb8b-4396a60ed9ae
Content-Type: application/json

{"reason":"retry after failed dependency download"}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/builds/311

{"id":"311","source_build":"77","state":"queued"}

idempotency key को authenticated principal, action type, target और request digest के साथ store करें। अगर वही caller वही key और वही request फिर भेजे, तो मूल परिणाम लौटाएँ। अगर वे अलग body या target के साथ key दोबारा इस्तेमाल करें, तो conflict लौटाएँ। globally shared key record एक tenant को दूसरे से टकरा सकता है, और request body को अनदेखा करने वाली key copy-paste की गलती को गलत कार्रवाई में बदल सकती है।

जब अनुरोध पसंदीदा resource state बताता हो, तब PUT या PATCH उपयोग करें। PATCH /v1/deployments/77 के साथ {"paused":true} तब ठीक हो सकता है जब resource उस field का मालिक हो। POST /v1/deployments/77/rollback किसी ऐसे command को बेहतर बताता है जिसमें नया execution, audit trail और संभवतः asynchronous result हो। केवल किसी की style guide को संतुष्ट करने के लिए command को PATCH में न ठूँसें।

अस्पष्टता से उबरने के लिए caller को पर्याप्त state लौटाएँ। अगर action asynchronous चलती है, तो operation ID लौटाएँ और उसकी प्रगति केवल पढ़ने वाला GET endpoint दें। तब GET को retry, poll और response header के अनुसार cache किया जा सकता है, और दुनिया बदले बिना ब्राउज़र में खोला जा सकता है।

मंजूरी क्रेडेंशियल इंजेक्ट होने से पहले होनी चाहिए

HTTP request मशीन से निकल जाने के बाद की मंजूरी केवल दिखावा है। client को response मिलने से पहले remote service काम कर सकती है, और failure response यह साबित नहीं करता कि उसने कुछ नहीं किया। फैसला वहीं रखें जहाँ request तैयार होती है, credentials लगने और bytes process से निकलने से पहले।

यह तब महत्वपूर्ण है जब कोई AI coding agent API कॉल करे। agent tool description से रूट को read मान सकता है, repository से पुराना URL कॉपी कर सकता है या ticket में दी गई सलाह पर चल सकता है। अगर उसके पास raw credentials हैं, तो इंसान के endpoint देखने से पहले ही वह कॉल कर सकता है। model से सावधान रहने को कहने वाला prompt authorization control नहीं है।

approval layer को normalized action model दें। उसमें कम से कम HTTP method, host, path, जहाँ उपलब्ध हो target identifier और छोटा consequence होना चाहिए। layer को actions का वर्गीकरण service contract से करना चाहिए, केवल method === "GET" से नहीं। revokeToken कॉल करने वाला legacy GET route, हटाए जाने तक POST /tokens/123/revoke जैसे approval path में ही जाना चाहिए।

व्यावहारिक mapping ऐसी दिख सकती है:

{
  "method": "GET",
  "url": "https://api.example.test/v1/tokens/tk_42/revoke",
  "semantic_action": "revoke credential",
  "target": "tk_42",
  "approval": "required",
  "reason": "legacy GET endpoint changes remote credential state"
}

approver को केवल hostname और हरा button न दिखाएँ। prompt में बताना चाहिए कि कॉल credential रद्द करती है और उस target का नाम होना चाहिए जिस पर असर पड़ेगा। अगर आपका system semantic action तय नहीं कर सकता, तो कॉल को unclassified मानें और मंजूरी माँगें। हर GET को केवल GET होने के कारण allowlist करना, मूल खामी को एक layer और नीचे बना देता है।

Sallyport का per-session authorization और per-call credential control, उसके HTTP channel का इस्तेमाल करने वाले agent के लिए इस सीमा पर रखा जा सकता है। महत्वपूर्ण डिज़ाइन निर्णय ऐप से स्वतंत्र है: vault holder अनुरोध चलाता है, जबकि agent को secret नहीं, उसका परिणाम मिलता है।

read को उपयोगी और write को गलती से शुरू करना कठिन रखें

साफ migration pattern discovery के लिए सुरक्षित GET बचाता है और कार्रवाई के लिए अलग write endpoint लाता है। आप human-friendly page, status endpoint या dry-run response रख सकते हैं, बिना fetch को command चलाने दिए।

report generator के लिए GET /reports/monthly सबसे हाल की पूरी हुई report और अभी की generation status लौटा सकता है। POST /reports/monthly/runs नई generation शुरू करता है। credential operation में GET /tokens/tk_42 metadata लौटा सकता है, जबकि POST /tokens/tk_42/revocations revocation event बनाता है। action query parameter की तुलना में अतिरिक्त path segment कम चतुर लगता है, लेकिन यह logs, clients और review screen को बहुत साफ बनाता है।

dry run को सटीक contract चाहिए। POST /deployments/77/rollback?dry_run=true फिर भी POST है, क्योंकि caller ने command evaluation माँगी है, भले ही वह कुछ commit न करे। planned target, अपेक्षित precondition और unresolved value लौटाएँ। GET /rollback?preview=true को command planning न चलाने दें, अगर planning में lock लेना, capacity reserve करना या provider से observable effect वाला संपर्क करना शामिल है।

कुछ टीमें पुराने integration बचाने के लिए पुराने GET को ऐसा HTML page लौटाने देती हैं जिसमें form POST को अपने-आप submit कर देता है। इससे जोखिम केवल browser में चला जाता है। ऐसा page इस्तेमाल करें जिसमें असल user interaction जरूरी हो और POST को application के लिए सही same-origin defense मिले। API client को साफ deprecation response और migration deadline मिलनी चाहिए, ऐसा browser document नहीं जिसे वह इस्तेमाल न कर सके।

उन कॉलर को जाँचें जो कभी मंजूरी नहीं माँगते

कोई रूट तब तक ठीक नहीं माना जा सकता जब तक आप उस automated behavior को न जाँच लें जिसने उसे असुरक्षित बनाया था। handler किसी service method को कॉल करता है, यह जाँचने वाले unit test काफी नहीं हैं। रूट को वैसे चलाकर देखें जैसे browser, timeout वाला HTTP client, crawler और agent उससे मिलेंगे।

हर migrated action के लिए isolated environment में ये जाँच चलाएँ:

1. पुराने GET को दो बार भेजें और पुष्टि करें कि वह दो action नहीं बना सकता। transition के दौरान उसे सुरक्षित रूप से fail होना चाहिए, केवल confirmation state दिखानी चाहिए या deprecation response लौटाना चाहिए।
2. ऐसे client का simulation करें जो dispatch के बाद response खो देता है, फिर वही idempotency key लगाकर POST retry करता है। पुष्टि करें कि service मूल action ID लौटाती है।
3. सुरक्षित status URL को बार-बार fetch करें और पुष्टि करें कि उससे कोई job, message, ledger entry या external call नहीं बनती।
4. expired approval या revoked session के साथ action की कोशिश करें और पुष्टि करें कि अनुरोध remote service तक कभी नहीं पहुँचता।
5. audit record देखें और सत्यापित करें कि उसमें केवल transport route नहीं, normalized action भी पहचाना गया है।

असहज बिंदु पर fault injection करें: server के action commit करने के बाद, लेकिन response भेजने से पहले। यहीं टीमों को पता चलता है कि उनका client blindly retry करता है या नहीं। अगर एकमात्र recovery strategy «इसे फिर आज़माएँ» है, तो contract ने caller को पर्याप्त जानकारी नहीं दी।

documentation example भी जाँचें। incident channel में कॉपी किया गया curl command operational interface बन जाता है। अगर उदाहरण GET इस्तेमाल करता है क्योंकि वह एक लाइन में आ जाता है, तो कोई उसे automate करेगा। सुरक्षित read उदाहरण और स्पष्ट action उदाहरण को साफ तौर पर अलग दिखाएँ।

रूट के साथ असर का भी ऑडिट करें

GET /v1/builds/77/retry 200 कहने वाली audit line कमजोर सबूत है। वह transport fact दर्ज करती है, पर business event छिपाती है। incident के दौरान जाँचकर्ता को फिर भी यह समझना पड़ता है कि कॉल ने build शुरू किया, पहले वाले को retry किया या केवल उसका state लौटाया।

दोनों layer दर्ज करें। मिलने वाला method और route रखें, क्योंकि legacy behavior मायने रखता है। इनके साथ semantic action, target, caller process या principal, approval decision, बिना secret material वाली credential identity, correlation ID और result reference दर्ज करें। asynchronous command के लिए operation ID या resulting resource ID लॉग करें, ताकि बाद की event मूल request से जुड़ सकें।

tamper-evident log तभी उपयोगी है जब भरोसा संदिग्ध हो जाने पर भी उसे verify किया जा सके। verification process को application के सामान्य read path से अलग रखें। Sallyport अपने session और call journal को write-blind encrypted hash-chained audit log से project करता है, और sp audit verify ciphertext पर उस chain को offline जाँचता है। जब किसी agent के पास external system को प्रभावित करने का अधिकार हो, तो ऐसी property की माँग करना उचित है।

ऑडिट retention को secret दर्ज करने का बहाना न बनने दें। request body में अक्सर credentials, token, personal data या command argument होते हैं, जिन्हें सामान्य activity log में नहीं होना चाहिए। जहाँ integrity evidence चाहिए, वहाँ normalized description और digest लॉग करें। संवेदनशील सामग्री केवल वहीं रखें जहाँ access control और retention rule उसका साथ दे सकें।

अपवाद को हमेशा दस्तावेज़ में रखने के बजाय हटाएँ

अंतिम स्थिति में कोई mutating GET route नहीं रहता, भले ही approval gateway अभी उसे पकड़ रहा हो। अपवाद को जीवित रखने से नया client, कॉपी किया गया URL या भविष्य का refactor classification table को bypass कर सकता है। compatibility layer का मालिक, caller inventory और पुराने form को स्वीकार करना बंद करने की तारीख होनी चाहिए।

सबसे अपरिवर्तनीय परिणाम देने वाले endpoint से शुरुआत करें। साफ POST contract, idempotency behavior, approval classification और effect-level audit record जोड़ें। फिर हर पुराने GET call को observable बनाएँ। जब आप बचे हुए callers का नाम बता सकें, तो उन्हें जानबूझकर बदलें, किसी छिपे integration को अचानक तोड़ें नहीं।

«हमारा client बेहतर जानता है» को सुरक्षा की property न मानें। GET अनुरोध उन system से होकर जाता है जो उसे दोहराने और जाँचने के लिए बनाए गए हैं। अपने write को write जैसा बनाएँ, इससे पहले कि उनमें से कोई system मदद करने का फैसला कर ले।