JSON Toolkit

API response की संरचना कैसी होनी चाहिए

मुख्य बात: Bare objects तब तक साफ़ रहते हैं जब तक metadata की ज़रूरत न पड़े; पूरे envelopes सुरक्षित पर शब्दबहुल होते हैं। अधिकतर प्रोजेक्ट्स के लिए परिणाम के लिए HTTP status और डेटा के लिए स्थिर envelope उपयोग करें।

मध्यम~4 मिनट पढ़ें2026-10-30 को प्रकाशित2026-10-30 को अपडेट किया गया
API response के तीन आकार और उनके समझौते

मुख्य बात: परिणाम 4xx/5xx status codes से बताएँ, payload को { "data": ..., "meta": ... } में रखें, और विफलता पर error envelope पर चले जाएँ; आंतरिक APIs के लिए यह काफ़ी है, और केवल उन सार्वजनिक प्लेटफ़ॉर्म्स को जिनके कई integrators हों JSON:API या OpenAPI चाहिए।

पहले सबसे बुरे विकल्प को हटाएँ: हमेशा 200 लौटाना और परिणाम code फ़ील्ड में रखना।

तीन आकार

A. बिना लिपटा object

{ "id": 1, "name": "demo", "price": 99 }

साफ़, और HTTP semantics काम करते हैं (404 तो 404 है)। पर जिस पल आपको pagination, warnings या trace id चाहिए, अनुबंध बदले बिना उन्हें रखने की जगह नहीं है।

B. स्थिर envelope

{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "abc", "took": 12 }
}

Payload और metadata अलग रहते हैं, इसलिए नया metadata data का आकार कभी नहीं बदलता। कीमत एक स्तर का nesting।

C. सब कुछ envelope (बचें)

{ "code": 0, "message": "success", "data": {...} }

आकार पाप नहीं है; आदत है। हर परिणाम के लिए status 200 का मतलब है CDNs, gateways, circuit breakers, retry policies और dashboards सब सफलता देखते हैं। फिर हर alert को कस्टम parsing चाहिए।

सिफ़ारिश

परिणाम के लिए HTTP status, payload के लिए envelope।

{
  "data": { "id": 1, "name": "demo" },
  "meta": { "requestId": "req_8f2a", "took": 12 }
}

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order does not exist or was deleted",
    "details": [{ "field": "id", "issue": "not_found" }]
  },
  "meta": { "requestId": "req_8f2a" }
}

Status 4xx या 5xx; code स्थिर और machine-readable; message इंसानों के लिए; details फ़ील्ड-स्तरीय form errors के लिए।

कठोर नियम

  1. List endpoints में pagination metadata होनी ही चाहिए। total या cursor के बिना pager नहीं बनता।
  2. खाली lists [] लौटाएँ, कभी null नहीं। null.map बार-बार होने वाला outage है।
  3. Timestamps ISO 8601 में offset के साथ। देखें timestamps के लिए कौन सा फ़ॉर्मैट।
  4. एक नामकरण परंपरा। snake_case या camelCase, सीमा पर एक बार बदला गया।
  5. पैसा integer minor units या strings में। 99.99 binary floating point में सटीक नहीं है।
  6. null को अनुपस्थित के साथ न मिलाएँ। देखें null या फ़ील्ड छोड़ें।

Specification कब अपनाएँ

  • कई integrators वाले सार्वजनिक प्लेटफ़ॉर्म: JSON:API या OpenAPI और एक साझा envelope
  • एक टीम की आंतरिक APIs: ऊपर वाला envelope काफ़ी है
  • मज़बूत अनुबंध: Schema पहले, संरचनाएँ उससे बनाई गईं

Specifications बहस बचाते हैं और onboarding की लागत घटाते हैं। पाँच लोगों की टीम के लिए JSON:API आमतौर पर नकारात्मक काम है।

FAQ

बिना लिपटे object और envelope के बीच चुनाव कैसे करूँ?

जब pagination, warnings या requestId चाहिए तो envelope उपयोग करें, ताकि meta बदले बिना data का आकार बदले बढ़ सके। बिना लिपटा object केवल तब लौटाएँ जब कोई metadata नहीं चाहिए और आप स्वीकार कर सकें कि बाद में फ़ील्ड जोड़ने से अनुबंध बदलेगा।

API को हर परिणाम के लिए 200 क्यों नहीं लौटाना चाहिए?

CDNs, gateways, circuit breakers, retry policies और dashboards सब HTTP status पढ़कर तय करते हैं कि cache करना है, retry करना है या alert करना है। हर जगह 200 होने पर वे विफलताओं को सफलता मानते हैं, और हर alert को व्यावसायिक code की कस्टम parsing चाहिए।

क्या list endpoints में pagination metadata होनी चाहिए?

हाँ। total या cursor के बिना pager नहीं बनता, और खाली lists को null के बजाय [] लौटाना ही चाहिए, वरना frontend की .map कॉल टूट जाती है।

आगे पढ़ें