सामान्य साक्षात्कार: आप एक ऐसा HTTP API कैसे डिज़ाइन करेंगे जिसे AI एजेंट्स विश्वसनीयता से उपयोग कर सकें?

प्रॉम्प्ट और दायरा

मानव डेवलपर्स के लिए डिज़ाइन किए गए प्रोजेक्ट-मैनेजमेंट API को ऐसे API में बदलें जिसे AI एजेंट्स विश्वसनीयता से कॉल कर सकें। ऑपरेशन विवरण, इनपुट, आउटपुट, पेजिनेशन, त्रुटियां, राइट पुष्टिकरण, दर सीमाएं और सुरक्षा की व्याख्या करें। यह प्रॉम्प्ट IETF जून 2026 “Agent-Friendly HTTP API Profile” Internet-Draft का संदर्भ देता है। यह केवल सूचनात्मक (Informational) है और अभी इस पर काम चल रहा है; यह किसी नए प्रोटोकॉल, पहचान (identity) या प्राधिकरण (authorization) तंत्र को परिभाषित नहीं करता है।

साक्षात्कारकर्ता क्या जांच रहा है

• मशीन-पठनीय विवरण को बाद में बनाए गए दस्तावेज़ के बजाय एक अनुबंध (contract) के रूप में मानना।
• स्थिर नामों, सख्त स्कीमा, सीमित प्रतिक्रियाओं और कर्सर पेजिनेशन के साथ गलत विकल्पों को कम करना।
• त्रुटियों, पुनः प्रयासों (retries), निष्प्रभाविता (idempotency), पूर्वावलोकन और पूर्ववत (undo) करने को कार्रवाई-योग्य संकेतों में बदलना।
• API की उपयोगिता को एजेंट की पहचान, प्राधिकरण और प्रॉम्प्ट-इंजेक्शन सुरक्षा से अलग करना।

उत्तर देने से पहले स्पष्ट करने योग्य प्रश्न

1. क्या एजेंट्स OpenAPI, एक MCP टूल लेयर, या एक कस्टम कैटलॉग के माध्यम से API की खोज करेंगे?
2. कौन से ऑपरेशन्स केवल-पठन (read-only) हैं और कौन से सूचित करते हैं, शुल्क लेते हैं, या स्थिति में बदलाव करते हैं?
3. क्या प्रतिक्रियाओं में फ़ील्ड चयन, कर्सर पेजिनेशन और अधिकतम पेज आकार की आवश्यकता है?
4. क्या क्लाइंट एक idempotency key प्रदान कर सकते हैं और टाइमआउट के बाद मूल परिणाम प्राप्त कर सकते हैं?
5. लौटाए गए कौन से फ़ील्ड्स में अविश्वसनीय उपयोगकर्ता सामग्री है जिसे नियंत्रण फ़ील्ड्स से अलग किया जाना चाहिए?

30-सेकंड का उत्तर ढांचा

API विवरण और HTTP व्यवहार को एक इनपुट अनुबंध के रूप में मानें। ऑपरेशन के नाम स्थिर और इरादे को स्पष्ट करने वाले रखें, अज्ञात इनपुट प्रॉपर्टीज को अस्वीकार करें, फ़ील्ड चयन के साथ छोटी प्रतिक्रियाएं लौटाएं, और कर्सर के साथ संग्रहों (collections) को पेजिनेट करें। त्रुटियों में स्थिर कोड, पुनः प्रयास करने की क्षमता और अगली कार्रवाइयां शामिल होनी चाहिए; राइट्स में idempotency keys, पूर्वावलोकन, पुष्टिकरण और पूर्ववत करने का समर्थन होना चाहिए। सर्वर सीमाएं, प्राधिकरण और ऑडिट लागू करता है; यह सुरक्षा निर्णयों को एजेंट को नहीं सौंप सकता। IETF दस्तावेज़ एक ड्राफ्ट चेकलिस्ट है, कोई प्रमाणीकरण प्रोटोकॉल नहीं।

चरण-दर-चरण गहन विश्लेषण

1. API और टूल लेयर्स को अलग करें

OpenAPI और इसी तरह के मशीन-पठनीय विवरण API लेयर के अंतर्गत आते हैं; MCP और अन्य टूल-कॉलिंग प्रोटोकॉल टूल लेयर के अंतर्गत आते हैं। पहले एक स्थिर, सत्यापन योग्य API अनुबंध बनाएं ताकि कई टूल लेयर्स इसका पुन: उपयोग कर सकें। किसी एक एजेंट के प्रॉम्प्ट या टूल के नाम को ही एकमात्र सुरक्षा सीमा न बनाएं।

2. विशिष्ट ऑपरेशन्स डिज़ाइन करें

Operation IDs स्थिर, संक्षिप्त और उद्देश्य स्पष्ट करने वाले होने चाहिए। एक बड़े टूल इंटरफ़ेस पर, task_create और task_update जैसे इकाई-प्रथम (entity-first) नाम एक साझा create_ उपसर्ग की तुलना में अलग पहचानने में आसान हो सकते हैं। विवरणों में यह स्पष्ट होना चाहिए कि किसी ऑपरेशन का उपयोग कब करना है और कब नहीं, इसके क्या दुष्प्रभाव (side effects) हैं, और कौन सा लुकअप ऑपरेशन अनुपलब्ध पहचानकर्ता प्राप्त करता है।

3. इनपुट और आउटपुट को सीमित करें

इनपुट स्कीमा को आवश्यक फ़ील्ड, बंद एनम (closed enums), लंबाई और ऐरे सीमाओं को परिभाषित करना चाहिए, और अज्ञात प्रॉपर्टीज को अस्वीकार करना चाहिए। प्रतिक्रियाएं डिफ़ॉल्ट रूप से छोटी होनी चाहिए और फ़ील्ड चयन या विस्तृतता (verbosity) का समर्थन करना चाहिए। क्लाइंट द्वारा कम डेटा का अनुरोध करने पर निर्भर न रहें; सर्वर ही लागत और संदर्भ के उपयोग को नियंत्रित करता है।

{
  "name": "task_create",
  "description": "Create a task; notifies the assignee.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["project_id", "title", "idempotency_key"],
    "properties": {
      "project_id": {"type": "string"},
      "title": {"type": "string", "maxLength": 200},
      "priority": {"type": "string", "enum": ["low", "medium", "high"]},
      "idempotency_key": {"type": "string", "maxLength": 128}
    }
  }
}

4. रीड्स और पेजिनेशन को पुनर्प्राप्त करने योग्य बनाएं

एजेंट से ऑफ़सेट की गणना करने के लिए कहने के बजाय एक अपारदर्शी (opaque) कर्सर लौटाएं। कर्सर को क्वेरी से बाइंड करें, इसे समाप्त (expire) होने दें, और उपयोग के लिए तैयार अगली कार्रवाई के साथ next_cursor लौटाएं। स्थिर क्रम, सशर्त अनुरोध और फ़ील्ड चयन डुप्लिकेट ट्रांसफर और संदर्भ के उपयोग को कम करते हैं।

5. त्रुटियों को मशीन द्वारा कार्रवाई-योग्य बनाएं

स्थिर कोड, संरचित विवरण और एक retryable फ़्लैग लौटाएं; उपयोगी होने पर अगले ऑपरेशन का लिंक शामिल करें। 429 प्रतिक्रिया में पुनः प्रयास में देरी का समय प्रदान किया जाना चाहिए, सत्यापन त्रुटियों में फ़ील्ड्स की पहचान होनी चाहिए, और लंबे समय तक चलने वाले जॉब्स में एक स्थिति URL प्रदान किया जाना चाहिए। प्राकृतिक भाषा लोगों की मदद करती है, लेकिन यह एकमात्र नियंत्रण सिमेंटिक्स नहीं हो सकती।

{
  "type": "https://api.example/problems/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "code": "RATE_LIMITED",
  "retryable": true,
  "retry_after_seconds": 30
}

6. राइट्स को सुरक्षित रखें

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

7. सुरक्षा और अवलोकनीयता (observability) सीमाएं निर्धारित करें

अप्रत्यक्ष प्रॉम्प्ट इंजेक्शन को कम करने के लिए उपयोगकर्ता या तीसरे पक्ष के टेक्स्ट को डेटा के रूप में चिह्नित करें और इसे विश्वसनीय नियंत्रण फ़ील्ड से अलग रखें। प्रतिक्रिया आकार, पेज आकार, पोलिंग और टूल नेमस्पेस को सीमित करें; उच्च जोखिम वाले ऑपरेशन्स के लिए न्यूनतम विशेषाधिकार (least privilege) और मानव पुष्टिकरण की आवश्यकता रखें। संवेदनशील सामग्री को लॉग किए बिना एक सहसंबंध आईडी (correlation ID), कर्ता (actor), प्रतिनिधिमंडल (delegation), परिणाम और पुनः प्रयासों को रिकॉर्ड करें।

8. मान्य करें और पुनरावृत्ति करें

ऑपरेशन-चयन सटीकता, पैरामीटर त्रुटियों, डुप्लिकेट राइट्स, पुनर्प्राप्त करने योग्य त्रुटियों, औसत प्रतिक्रिया आकार, संदर्भ उपयोग, 429 के बाद सफलता और पुष्टिकरण कवरेज को मापने के लिए निश्चित कार्य सेट का उपयोग करें। विवरण, स्कीमा, त्रुटियों और प्रतिक्रियाओं का वर्ज़न बनाएं। मानकों के अनुपालन का वादा करने के बजाय ड्राफ्ट की सिफारिशों को एक आंतरिक चेकलिस्ट में बदलें।

उच्च गुणवत्ता वाला नमूना उत्तर

मैं API विवरण को प्राथमिक अनुबंध मानूंगा और इसके इर्द-गिर्द HTTP व्यवहार डिज़ाइन करूंगा। Operation IDs स्थिर होंगे और इकाई तथा इरादे को व्यक्त करेंगे; विवरण उपयोग की शर्तों, निषिद्ध मामलों और दुष्प्रभावों को स्पष्ट करेंगे। इनपुट स्कीमा अज्ञात फ़ील्ड्स को अस्वीकार करेंगे और एनम, लंबाई, ऐरे और पेजों को सीमित करेंगे। संग्रह अपारदर्शी कर्सर और स्थिर क्रम का उपयोग करेंगे, जबकि प्रतिक्रियाएं छोटी और फ़ील्ड-चयन योग्य होंगी।

त्रुटियों में एक स्थिर कोड, पुनः प्रयास करने की क्षमता, retry_after और अगली कार्रवाई शामिल होगी। राइट्स के लिए idempotency keys आवश्यक होंगी और वे टाइमआउट के बाद मूल परिणाम लौटाएंगी; उच्च जोखिम वाले राइट्स पूर्वावलोकन, पुष्टिकरण या पूर्ववत करने का समर्थन करेंगे। सर्वर एजेंट द्वारा टेक्स्ट निर्देशों का पालन करने पर भरोसा करने के बजाय प्राधिकरण, दर सीमाएं, आकार और ऑडिट लागू करेगा। उपयोगकर्ता सामग्री को नियंत्रण फ़ील्ड्स से अलग रखा जाएगा, और टूल प्रदाता सहसंबंध आईडी के साथ अलग नेमस्पेस का उपयोग करेंगे।

अंत में, गलत विकल्पों, पैरामीटर त्रुटियों, डुप्लिकेट राइट्स, प्रतिक्रिया आकार, पुनः प्रयास की सफलता और पुष्टिकरण कवरेज के लिए एक टास्क सेट का मूल्यांकन करें। IETF दस्तावेज़ बिना किसी प्रमाणीकरण या प्राधिकरण प्रोटोकॉल वाला एक सूचनात्मक जून 2026 ड्राफ्ट है, इसलिए मैं इसे आंतरिक वर्ज़निंग और रोलबैक के साथ एक डिज़ाइन चेकलिस्ट के रूप में उपयोग करूंगा।

सामान्य गलतियाँ

• प्रोफ़ाइल को एक नया पहचान या प्राधिकरण प्रोटोकॉल कहना।
• OpenAPI, स्कीमा, त्रुटियों और दुष्प्रभावों को अस्पष्ट छोड़ते हुए केवल प्रॉम्प्ट्स को अनुकूलित करना।
• एजेंट से प्रतिक्रिया का आकार सीमित करने या पेजिनेशन ऑफ़सेट की गणना करने के लिए कहना।
• उन राइट्स से idempotency, पूर्वावलोकन, पुष्टिकरण, या पूर्ववत करने की सुविधा को छोड़ देना जिन्हें पुनः प्रयास किया जा सकता है।
• लौटाए गए उपयोगकर्ता टेक्स्ट को विश्वसनीय निर्देश फ़ील्ड्स में डालना और अप्रत्यक्ष प्रॉम्प्ट इंजेक्शन की अनदेखी करना।

अनुवर्ती प्रश्न और उत्तर

केवल अधिक विस्तृत दस्तावेज़ क्यों न लिखें?

एक एजेंट प्रत्येक चरण पर मशीन-पठनीय विवरणों और प्रतिक्रियाओं में से चयन करता है। स्थिर फ़ील्ड्स, एनम्स, त्रुटि फ़्लैग्स और कर्सर को निष्पादित करना पूरे गद्य में बिखरी सलाह की तुलना में आसान है; दस्तावेज़ीकरण मनुष्यों और माइग्रेशन के लिए उपयोगी बना रहता है।

सुरक्षा का स्वामित्व किस परत के पास है, API या MCP?

API को प्रमाणीकरण, प्राधिकरण, दर सीमाएं और ऑडिट लागू करना चाहिए। एक टूल लेयर जोखिम, नेमस्पेस और पुष्टिकरण को सीमित कर सकती है, लेकिन यह सर्वर-साइड एक्सेस कंट्रोल की जगह नहीं ले सकती।

आप कैसे तय करते हैं कि किन राइट्स के लिए पुष्टिकरण की आवश्यकता है?

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

यदि विवरण तीसरे पक्ष की सामग्री से दूषित हो जाएं तो क्या होगा?

तीसरे पक्ष के टेक्स्ट को स्पष्ट डेटा फ़ील्ड्स में रखें और इसे टूल परिभाषाओं या अनुमतियों को बदलने से रोकें। प्रदाता के नेमस्पेस को अलग करें, फ़िंगरप्रिंट पिन करें, वर्ज़न्स का ऑडिट करें और सर्वर पर प्राधिकरण की पुन: जांच करें।