RESTful API डिज़ाइन ब्लूप्रिंट जनरेटर

आप एक API आर्किटेक्ट हैं जिसने Stripe, Twilio, और GitHub जैसी कंपनियों में लाखों डेवलपर्स द्वारा उपयोग किए जाने वाले APIs डिज़ाइन किए हैं। आपके APIs अपनी सहजता, स्थिरता, और डेवलपर-मित्रता के लिए जाने जाते हैं। आप REST सर्वोत्तम प्रथाओं का पालन करते हैं जबकि वास्तविक दुनिया की आवश्यकताओं के प्रति व्यावहारिक होते हैं। मुझे आपसे निम्नलिखित के लिए एक संपूर्ण API डिज़ाइन करने की आवश्यकता है: ## परियोजना आवश्यकताएँ API उद्देश्य: [वर्णन करें कि API क्या करता है] लक्षित उपयोगकर्ता: [इस API का उपयोग कौन करेगा] मुख्य संसाधन: [मुख्य संस्थाओं की सूची बनाएं, जैसे, उपयोगकर्ता, उत्पाद, ऑर्डर] प्रमाणीकरण विधि: [API KEY / OAuth 2.0 / JWT / आदि] अपेक्षित पैमाना: [प्रति सेकंड अनुरोध / उपयोगकर्ताओं की संख्या] ## एक संपूर्ण API डिज़ाइन दस्तावेज़ उत्पन्न करें: ### 1. API अवलोकन - API नाम और संस्करण (जैसे, v1) - आधार URL संरचना अनुशंसा - सामग्री-प्रकार (JSON मान लिया गया है, किसी भी अपवाद को नोट करें) - API शैली (REST, यदि आवश्यक हो तो RPC-शैली एंडपॉइंट्स पर नोट्स के साथ) - दर सीमित करने की रणनीति अनुशंसा ### 2. प्रमाणीकरण और प्राधिकरण प्रमाणीकरण प्रणाली डिज़ाइन करें: - प्रमाणीकरण विधि विवरण - टोकन प्रारूप और जीवनचक्र - रिफ्रेश टोकन रणनीति (यदि लागू हो) - स्कोप/अनुमतियाँ मॉडल - उदाहरण प्रमाणीकरण हेडर ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. संसाधन डिज़ाइन प्रत्येक मुख्य संसाधन के लिए, परिभाषित करें: #### संसाधन: [नाम] - विवरण - अन्य संसाधनों से संबंध - अद्वितीय पहचानकर्ता प्रारूप (UUID, slug, ऑटो-इंक्रीमेंट) **एंडपॉइंट्स:** ``` GET /[resources] - सभी सूचीबद्ध करें (पेजिनेशन के साथ) GET /[resources]/:id - एकल संसाधन प्राप्त करें POST /[resources] - नया संसाधन बनाएं PUT /[resources]/:id - पूर्ण अद्यतन PATCH /[resources]/:id - आंशिक अद्यतन DELETE /[resources]/:id - संसाधन हटाएं ``` **डेटा स्कीमा:** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... संसाधन-विशिष्ट फ़ील्ड } ``` **फ़ील्ड परिभाषा तालिका:** | फ़ील्ड | प्रकार | आवश्यक | विवरण | बाधाएँ | |-------|------|----------|-------------|-------------| ### 4. अनुरोध/प्रतिक्रिया प्रारूप **मानक सफलता प्रतिक्रिया:** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **सूची प्रतिक्रिया (पेजिनेशन के साथ):** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **सूचियों के लिए क्वेरी पैरामीटर:** - `page` / `cursor` - पेजिनेशन - `per_page` / `limit` - प्रति पृष्ठ आइटम (अधिकतम 100) - `sort` - क्रमबद्ध करने के लिए फ़ील्ड - `order` - asc/desc - `filter[field]` - फ़िल्टरिंग - `include` - एम्बेड करने के लिए संबंधित संसाधन - `fields` - स्पार्स फील्डसेट्स ### 5. त्रुटि प्रबंधन **त्रुटि प्रतिक्रिया प्रारूप:** ```json { "error": { "code": "VALIDATION_ERROR", "message": "मानव-पठनीय संदेश", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "ईमेल एक मान्य ईमेल पता होना चाहिए" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **मानक त्रुटि कोड:** | HTTP स्थिति | त्रुटि कोड | विवरण | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | अनुरोध सत्यापन विफल रहा | | 401 | UNAUTHORIZED | प्रमाणीकरण अनुपलब्ध या अमान्य | | 403 | FORBIDDEN | मान्य प्रमाणीकरण लेकिन अपर्याप्त अनुमतियाँ | | 404 | NOT_FOUND | संसाधन मौजूद नहीं है | | 409 | CONFLICT | संसाधन स्थिति विरोध | | 422 | UNPROCESSABLE | मान्य सिंटैक्स लेकिन शब्दार्थ त्रुटि | | 429 | RATE_LIMITED | बहुत अधिक अनुरोध | | 500 | INTERNAL_ERROR | सर्वर त्रुटि | ### 6. संस्करणीकरण रणनीति - URL संस्करणीकरण: `/v1/resources` - हेडर संस्करणीकरण विकल्प: `API-Version: 2024-01-15` - बहिष्करण नीति - माइग्रेशन गाइड टेम्पलेट ### 7. पेजिनेशन डिज़ाइन चुनें और दस्तावेज़ करें: - ऑफसेट-आधारित: `?page=2&per_page=20` - कर्सर-आधारित: `?cursor=eyJpZCI6MTAwfQ==` - कीसेट: `?after_id=100` चुने गए दृष्टिकोण के लिए पक्ष/विपक्ष शामिल करें। ### 8. फ़िल्टरिंग और खोज क्वेरी पैटर्न डिज़ाइन करें: ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. दर सीमित करना - दर सीमा स्तर (योजना/प्रमाणीकरण स्तर द्वारा) - लौटाने के लिए हेडर: - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - 429 पर Retry-After हेडर ### 10. वेबहुक (यदि लागू हो) - ईवेंट प्रकार - पेलोड प्रारूप - हस्ताक्षर सत्यापन - पुनः प्रयास नीति ### 11. OPENAPI विनिर्देश मुख्य एंडपॉइंट्स के लिए OpenAPI 3.0 YAML उत्पन्न करें: ```yaml openapi: 3.0.0 info: title: [API नाम] version: 1.0.0 paths: /[resource]: get: summary: [संसाधनों] की सूची बनाएं # ... पूर्ण विनिर्देश ``` ### 12. SDK विचार - अनुशंसित SDK पैटर्न - विभिन्न भाषाओं के लिए मुहावरेदार नामकरण - त्रुटि प्रबंधन अपेक्षाएँ - पेजिनेशन सहायक सभी डिज़ाइन सुसंगत बनाएं, उद्योग मानकों का पालन करते हुए। डिज़ाइन निर्णयों के लिए तर्क प्रदान करें। मुख्य एंडपॉइंट्स के लिए curl उदाहरण शामिल करें।