Destructive API Parameters: डिलीट से पहले validation करें

जब कोई request syntax की दृष्टि से सही दिखती है, तब AI agents बहुत आसानी से विनाशकारी API calls कर देते हैं। सही JSON body, परिचित account name और सफल lookup से यह साबित नहीं होता कि agent सही object डिलीट करने वाला है। किसी भी बाहरी request से data remove, revoke, disconnect, cancel या overwrite करने से पहले service के विरुद्ध identity, ownership, scope और freshness की जांच करें।

मैंने सावधान engineers को किसी request को «इस test environment को डिलीट करें» के रूप में पढ़ते देखा है, जबकि API ने उसे «इस organization के हर environment को डिलीट करें» समझा। संकीर्ण अर्थ में code में कोई bug नहीं था। उसने loosely formed selector स्वीकार किया, गलत account से name resolve किया या run में पहले fetch किए गए data पर भरोसा किया। Autonomous agent ऐसी सामान्य गलतियां तेज़ी से और अधिक confidence के साथ करता है।

यह model से अधिक सावधान रहने को कहने का मामला नहीं है। Agent के proposed request और credentialed request के बीच deterministic gate रखें। Gate को default रूप से ambiguity reject करनी चाहिए और human से वास्तविक target तथा effect की मंज़ूरी लेनी चाहिए।

सही तरीके से बना request भी गलत object को target कर सकता है

किसी request को भेजने लायक सुरक्षित मानने से पहले चार अलग-अलग बातें तय करें: resource सही type का है, उसका immutable identifier अपेक्षित है, वह approved parent account का है और operation approved set को ही प्रभावित करेगा। Teams अक्सर इन चारों बातों को एक lookup में मिला देती हैं। Deletion में गड़बड़ी की शुरुआत इसी shortcut से होती है।

मान लें कि कोई service display name और ID दोनों देती है:

{
  "id": "env_7d3a",
  "name": "staging",
  "account_id": "acct_blue",
  "state": "active"
}

staging खोजने वाले agent को केवल एक candidate मिला है, उसे डिलीट करने की अनुमति नहीं। कई accounts में staging environment हो सकता है। एक ही account में भी पुराना object हटने के बाद वही नाम दोबारा इस्तेमाल हो सकता है। सुरक्षित action request वही है जो लौटाए गए immutable ID से बने और expected parent ID से जांची जाए।

यह अंतर तब सबसे महत्वपूर्ण होता है जब API /accounts/{account_id}/environments/{environment_id} जैसा parent path support करती है। दोनों segments की जांच करें। केवल इसलिए ownership न मानें कि ID किसी पुराने search response में दिखी थी या agent ने अपनी plan में वही account name डाल दिया था। Action URL में मौजूद parent authorization boundary का हिस्सा है।

Resource type की अपनी जांच होनी चाहिए। APIs अक्सर shared search endpoint इस्तेमाल करती हैं या mixed records लौटाती हैं। staging नाम का result environment, project, access group या saved template हो सकता है। अगर service के अलग-अलग delete endpoints हैं, तो returned type verify करने के बाद ही endpoint चुनें। Model द्वारा बनाए गए type string को जोड़कर endpoint न बनाएं।

अंत में, candidates देखने से पहले expected effect तय करें। «पुराने deployment को हटाएं» का मतलब deployment record डिलीट करना, running job रोकना, उससे जारी token revoke करना या पूरा environment डिलीट करना हो सकता है। इन effects के लिए एक generic delete operation नहीं हो सकता। Action contract में requested verb और object type को स्पष्ट करें।

नाम लोगों की मदद करते हैं, IDs request को नियंत्रित करती हैं

Resource को address करने के लिए immutable ID इस्तेमाल करें, लेकिन approval देने वाले व्यक्ति को इतनी human context दें कि वह गलत चुनाव पकड़ सके। केवल env_7d3a लिखा approval card बिना सोचे मंज़ूरी देने को बढ़ावा देता है। केवल staging लिखा card ambiguity पैदा करता है। Operator के सामने दोनों रखें, साथ में parent account और operation का परिणाम भी दिखाएं।

उपयोगी target record कुछ ऐसा हो सकता है:

{
  "operation": "delete_environment",
  "account": {"id": "acct_blue", "name": "Blue Team"},
  "target": {"id": "env_7d3a", "name": "staging", "type": "environment"},
  "expected_state": "active",
  "effect": "permanently removes this environment and its managed resources"
}

Account display name से operator देख सकता है कि agent गलत tenant में चला गया है। Resource name से object पहचानने में मदद मिलती है। IDs request को अस्पष्ट नहीं रहने देतीं। Stated effect approval की एक आम गलती रोकता है: व्यक्ति सोचता है कि उसने reversible stop action को मंज़ूरी दी, जबकि provider data हटाने वाला है।

किसी name को first search result से resolve न करें। Search endpoints अक्सर relevance के आधार पर results rank करते हैं, partial matches लौटाते हैं या pagination करते हैं। यदि task exact name देता है, तो parent account और expected type से filter करने के बाद ठीक एक candidate होना चाहिए। Zero candidates पर fail करें। एक से अधिक candidates पर भी fail करें। Agent से किसी एक को चुनने को कहना समाधान नहीं है, क्योंकि उसके पास दोनों में अंतर करने वाला evidence नहीं है।

Case handling के लिए भी service-specific rule चाहिए। कुछ providers names को case-sensitive मानते हैं, जबकि दूसरे उन्हें normalize करते हैं। अपनी तरफ name normalize करके यह न मानें कि provider भी वही करेगा। Provider द्वारा लौटाए गए resource को authority मानें और approval record में exact returned label रखें।

Tags, labels और descriptions context हैं, identity नहीं। वे अक्सर बदलते हैं और users उनमें लगभग कुछ भी लिख सकते हैं। temporary=true जैसा tag reviewed list को छोटा कर सकता है, लेकिन उसे account binding या immutable resource ID की जगह इस्तेमाल नहीं करना चाहिए।

Agent approval मांगने से पहले scope ठोस होना चाहिए

Destructive operation का scope तब भी होता है जब request body में केवल एक ID हो। Scope में parent account, चुने गए resources, वे child resources जिन्हें provider अपने-आप हटाता है और selection को बढ़ाने वाला कोई filter शामिल होता है। किसी से approval लेने से पहले इस scope को ठोस बनाएं।

Single object deletion का contract सरल है: एक immutable ID, एक expected parent और एक resource type। Bulk deletion के लिए अलग contract चाहिए। पहले resolved set तैयार हो, फिर उस set या human द्वारा जांचे जा सकने वाले bounded summary के लिए approval लिया जाए। Selector को सीधे destructive endpoint पर भेजने से external service approval के बाद scope तय करती है।

मान लें agent यह request प्रस्तावित करता है:

{
  "account_id": "acct_blue",
  "filter": {"label": "cleanup-candidate"},
  "delete": true
}

इस body में operator के लिए सबसे जरूरी तथ्य छिपा है: अभी कौन से resources match करते हैं। Read-only list call से इसे expand करें, जिस pagination को पूरी तरह inspect नहीं किया गया उसे reject करें और result को IDs में normalize करें। फिर count और names वाले छोटे sample को दिखाएं। Set approved limit से बड़ा हो तो रुकें और नया instruction मांगें।

कभी भी omitted filter का मतलब «all» न होने दें। Request schemas में required empty list और absent selector को अलग रखें। इससे बेहतर है कि agent action interface में destructive endpoints को filters स्वीकार करने से ही रोक दें। Bulk work के लिए gateway केवल resolved IDs की list स्वीकार करे।

एक व्यावहारिक रूप इस तरह हो सकता है:

{
  "operation": "delete_resources",
  "account_id": "acct_blue",
  "resource_type": "snapshot",
  "resource_ids": ["snap_104", "snap_105"],
  "selection_observed_at": "2025-03-08T14:32:11Z"
}

जब तक workflow इसे स्पष्ट रूप से allow न करता हो, empty resource_ids array को reject करें। Duplicate IDs reject करें। दूसरे account की IDs reject करें। उस operation के लिए approved maximum count लागू करें जिसे व्यक्ति ने मंज़ूरी दी है। Limit review का विकल्प नहीं है, लेकिन malformed loop को दो-resource cleanup से thousand-resource incident बनने से रोकता है।

Cascades भी scope का हिस्सा हैं। यदि project डिलीट करने से repositories, deploy keys, environments या billing records डिलीट होते हैं, तो approval से पहले यह बात बताएं। यदि provider केवल preflight call के बाद cascade details दिखाता है, तो उस response को सुरक्षित रखें और agent से उसे दिखाने को कहें। Dependent objects वाले project के लिए «Delete project» बहुत अस्पष्ट है।

जब समय target बदल सकता हो, service को दो बार पढ़ें

Preflight read intent की पुष्टि करता है, लेकिन object को freeze नहीं करता। Validation और deletion के बीच resource बदल सकता है, account बदल सकता है या गायब हो सकता है। Sensitive operations के लिए mutation से ठीक पहले target को फिर पढ़ें और provider concurrency control देता हो तो उसका इस्तेमाल करें।

HTTP में इसके लिए standard mechanism है। RFC 9110 If-Match के साथ conditional requests परिभाषित करता है: server तभी requested method चलाता है जब current representation client द्वारा दिए गए entity tag से मेल खाए। GET से ETag मिल सकता है और बाद का DELETE वही exact value भेज सकता है।

GET /v1/accounts/acct_blue/environments/env_7d3a HTTP/1.1
Authorization: Bearer [injected credential]

HTTP/1.1 200 OK
ETag: "v42"
Content-Type: application/json

{"id":"env_7d3a","account_id":"acct_blue","name":"staging","state":"active"}

Body की तुलना approved target से करने के बाद भेजें:

DELETE /v1/accounts/acct_blue/environments/env_7d3a HTTP/1.1
If-Match: "v42"
Authorization: Bearer [injected credential]

यदि service 412 Precondition Failed लौटाती है, तो इसे सफल guardrail मानें। बिना condition के delete दोबारा करने को agent से न कहें। Resource फिर fetch करें, approved facts से तुलना करें और relevant fact बदलने पर fresh approval मांगें। Version conflict इस बात का evidence है कि पुरानी approval अब लागू न हो।

कुछ services HTTP ETags की जगह revision numbers, update timestamps, generation fields या request tokens इस्तेमाल करती हैं। Provider का documented mechanism अपनाएं। यदि कोई mechanism नहीं है, तो final read और write के बीच का समय घटाएं, action को serial बनाएं और स्वीकार करें कि target के अपरिवर्तित रहने का प्रमाण नहीं दिया जा सकता। यह सीमा तय करनी चाहिए कि unattended deletion की अनुमति देनी है या नहीं।

Successful GET को mutate करने की permission न समझें। Read credential वह अधिक data देख सकता है जिसे write credential बदल नहीं सकता, और authorization object state से स्वतंत्र रूप से बदल सकती है। Mutation response ही तय करता है कि provider ने request स्वीकार की या नहीं।

Validation credential boundary पर होनी चाहिए

केवल agent prompt या generated code में की गई validation advisory है। Credential रखने या inject करने वाले component को checks लागू करनी चाहिए, क्योंकि outbound request रोकने का आखिरी अवसर उसी के पास होता है।

इस boundary को free-form URL और arbitrary headers के बजाय structured action proposal मिलना चाहिए। एक narrow action definition में account ID, resource ID, method, expected type और expected version जैसे fields अनिवार्य किए जा सकते हैं। यह validated segments से outgoing path बना सकती है और scope बढ़ाने वाले query parameters reject कर सकती है।

Agent से complete URL स्वीकार करके बाद में उसमें से safety निकालने की कोशिश न करें। URL encoding, repeated query keys, alternate hostnames और path normalization इसे parser contest बना देते हैं। Typed fields स्वीकार करें, हर field को provider contract से validate करें और URL खुद बनाएं। Request bodies पर भी यही नियम लागू है। ऐसे blob को pass through करने के बजाय known body shape generate करें जिसके fields आपने जांचे नहीं हैं।

एक minimal gate यह sequence लागू कर सकता है:

1. Confirm करें कि requested operation allowlist में मौजूद है और उसका method design से destructive है।
2. हर claimed target को उसी parent account के तहत read call से resolve करें।
3. Returned ID, type, parent और required state की structured proposal से तुलना करें।
4. Resolved effect के लिए approval लें, फिर freshness दोबारा जांचकर mutation भेजें।
5. Result रिकॉर्ड करें, जिसमें provider लौटाए तो उसका request ID भी शामिल हो।

Allowlist छोटी रखें। raw_http नाम का generic escape hatch इस लेख की हर check को बेकार कर देता है, क्योंकि agent arbitrary destinations, methods और bodies फिर से डाल सकता है। Engineers endpoint missing होने पर ऐसे escape hatches जोड़ते हैं और तब तक भूल जाते हैं जब तक वह उन guardrails को bypass नहीं कर देता जिन्हें वे लागू समझते थे।

Credentials agent context से बाहर रहें। Agent को permitted action का result चाहिए, bearer token नहीं जिसे वह curl command, log या third-party integration में copy कर सके। Sallyport अपने HTTP actions में यही तरीका अपनाता है: वह credential को encrypted vault में रखता है, request खुद चलाता है और result agent को लौटाता है।

DELETE का मतलब यह नहीं कि request सरल या reversible है

HTTP method names पूरा business effect नहीं बताते। RFC 9110 के अनुसार DELETE origin server से target resource और उसकी current functionality के बीच association हटाने को कहता है। RFC यह promise नहीं करता कि data तुरंत गायब होगा, related data बचा रहेगा या आपके खास API में retry harmless होगी।

Actual effect provider documentation में होना चाहिए। कुछ APIs object को बाद में हटाने के लिए mark करती हैं। कुछ tombstone बनाती हैं। कुछ उसे parent से अलग करती हैं। कुछ children तक cascade करती हैं। किसी operation को low risk मानने से पहले endpoint के response codes और lifecycle notes पढ़ें।

Provider स्पष्ट रूप से document न करे तो DELETE के साथ body न भेजें। RFC 9110 कहता है कि DELETE request में मिले content का कोई generally defined semantics नहीं है और implementations request reject कर सकती हैं। किसी provider का deletion API body में filters पर निर्भर हो सकता है, लेकिन documented client path से इसकी extra testing होनी चाहिए। इसे agent से free-form selectors pass करने का बहाना न बनाएं।

Retries को भी उतनी ही सावधानी चाहिए। Network timeout unknown outcome बनाता है: client का इंतज़ार बंद करने के बाद provider deletion पूरी कर चुका हो सकता है। तुरंत retry करने से misleading logs बन सकते हैं, खराब design वाले endpoint पर दूसरा effect हो सकता है या name से retry resolve होने पर replacement resource डिलीट हो सकता है।

Unknown result में पहले inspect करें। Exact parent के तहत exact immutable ID query करें। यदि object मौजूद नहीं है और provider का deletion model इस interpretation को support करता है, तो operation को first response uncertain लेकिन completed के रूप में रिकॉर्ड करें। यदि object अभी मौजूद है, तो retry तय करने से पहले उसकी state और उपलब्ध होने पर provider request history जांचें। जिन operations में idempotency key support हो, वहां उसे reuse करें, लेकिन provider द्वारा न दी गई idempotence खुद न गढ़ें।

204 No Content केवल यह बताता है कि server ने endpoint द्वारा परिभाषित HTTP interaction स्वीकार कर पूरी की। इससे यह साबित नहीं होता कि downstream cleanup पूरा हो गया है। Agent की अगली action deletion के पूरा होने पर निर्भर हो तो empty response body को guarantee मानने के बजाय documented operation status या resource state poll करें।

Approval में raw transport नहीं, परिणाम दिखना चाहिए

जब approval में effect सामान्य भाषा में लिखा हो और verification के लिए जरूरी identifiers शामिल हों, तो humans बेहतर निर्णय लेते हैं। Method, path और JSON body API engineer के लिए उपयोगी हैं, लेकिन वे गलत target पकड़ने वाले व्यक्ति पर बहुत parsing work डालते हैं।

Single resource के लिए approval में बताएं कि क्या बदलेगा, parent account का नाम दें, resource name और ID दिखाएं और irreversible या cascading effects बताएं। Bulk operation में count, सीमित sample, list बनाने वाला selection rule और यह तथ्य दिखाएं कि final action rule के बजाय frozen IDs का इस्तेमाल करेगा।

लंबे agent run की शुरुआत में एक broad approval लेकर बाद की हर delete पर उसे इस्तेमाल न करें। Agent resources खोजता है तो target set बदलता रहता है। Approval को session और resolved action से bind करें। यदि agent process बदलता है, तो approval चुपचाप ऐसे नए process के साथ नहीं जानी चाहिए जिसके code या instructions अलग हो सकते हैं।

दूसरी समस्या approval fatigue है। हर harmless read पर click करवाने से व्यक्ति बिना पढ़े click करना सीखता है और फिर dangerous delete को भी वही visual weight मिलता है। जहां उचित हो reads को noninteractive रखें, नए चल रहे agent के लिए session authorization लें और per-action confirmation केवल credentials या destructive effect वाली actions के लिए रखें। कम prompts देखने वाला व्यक्ति महत्वपूर्ण prompts को ध्यान से देख सकता है।

Approval record की स्पष्ट expiry होनी चाहिए। Validation के बाद agent जितनी देर इंतज़ार करता है, preflight का अर्थ उतना कम होता जाता है। Action तुरंत न चल सके तो उसे फिर resolve करें और approval दोबारा मांगें। Cleanup job के दौरान यह सख्त लग सकता है, लेकिन यह समझाने से कम महंगा है कि एक घंटे पहले की approval उस resource पर लागू क्यों हुई जिसे बाद में फिर से बनाया जा चुका था।

Audit evidence को secrets दिखाए बिना decision दोबारा बनाना चाहिए

उपयोगी audit trail केवल «क्या request हुई?» का जवाब नहीं देता। उससे यह फिर से समझ आना चाहिए कि agent ने क्या propose किया, mutation से पहले service ने क्या बताया, व्यक्ति ने किसे मंज़ूरी दी, gateway ने क्या भेजा और service ने क्या लौटाया।

केवल raw request string नहीं, normalized fields capture करें। Action name, agent session identity, parent account ID, resource IDs, expected versions, selection timestamp, approved effect, approval time, outbound method और path, response status तथा provider request ID रिकॉर्ड करें। Request material में sensitive values हों तो hashes या redacted forms रखें। Authorization headers की copy रखने वाला audit log दूसरा credential store बना देता है।

Preflight response या उसका integrity-protected digest सुरक्षित रखें। उसके बिना बाद का reviewer यह नहीं बता सकता कि agent ने गलत object validation failure के कारण डिलीट किया, validation के बाद object बदल गया या external service documented behavior से अलग चली। अंतर से तय होता है कि क्या सुधारना है।

जब agent और action gateway एक ही machine पर चलते हों, तब tamper evidence महत्वपूर्ण है। Mutable text log को incident पैदा करने वाला process बदल सकता है। Sallyport अपने Sessions और Activity journals encrypted, hash-chained audit log से बनाता है और sp audit verify vault key के बिना offline chain जांच सकता है। इससे खराब approval सही नहीं बनती, लेकिन record में बाद का बदलाव छिपाना कठिन हो जाता है।

Failed requests पर भी logging जांचें। Rejections, expired approvals, version conflicts और malformed IDs दिखाते हैं कि controls ने वास्तव में work रोका या नहीं। केवल successes से भरा journal यह बहुत कम बताता है कि gate dangerous request को रोक पाएगा या नहीं।

Destructive actions को narrow contracts की तरह बनाएं

सबसे सुरक्षित API action उबाऊ रूप से narrow होती है। वह एक known operation स्वीकार करती है, known parent और object ID अनिवार्य करती है, preflight check चलाती है और उसका effect स्पष्ट होता है। General interfaces productive लगते हैं, जब तक agent ऐसा request न कर दे जिसकी आपने कल्पना नहीं की थी और आपका एकमात्र बचाव यह उम्मीद रह जाए कि operator कोई subtle parameter देख लेगा।

ऐसे actions की inventory बनाकर शुरू करें जो delete, revoke, rotate, disable, overwrite, publish या charges trigger कर सकती हैं। हर action के लिए immutable target fields, parent fields, allowed states, cascade behavior, freshness mechanism, retry behavior और approval text लिखें। यदि आप ये तथ्य स्पष्ट रूप से नहीं बता सकते, तो action अभी autonomous agent को न दें।

फिर gate के माध्यम से जानबूझकर खराब inputs चलाएं: wrong account के तहत valid resource ID, दो results वाला matching display name, stale ETag, empty bulk list, omitted filter, उसी name से फिर बनाया गया target और send के बाद timeout। यही inputs दिखाते हैं कि boundary meaning validate करती है या केवल JSON।

Ambiguity को agent से लंबी plan लिखवाकर हल न करें। Action contract में ambiguity को represent करना ही संभव न रहने दें। Agent intent propose कर सकता है और evidence जुटा सकता है। Credential boundary को तय करना चाहिए कि evidence इस account के तहत, इसी समय, एक अनुमत effect को नाम देता है या नहीं। यह विभाजन आपको ऐसा system देता है जिसे routine request के समय inspect किया जा सकता है और कठिन request के समय भरोसा किया जा सकता है।