REST API की बुनियादी बातें

यह क्यों ज़रूरी है

REST conventions से आप request भेजने से पहले ही expected behaviour का अनुमान लगा सकते हैं: create 201 Created लौटाता है, delete हुआ resource फिर नहीं मिलता, unsupported method 405 से reject होता है। जहाँ भी API बिना document किए कोई convention तोड़ता है, वहाँ client developers ऐसा code लिख सकते हैं जो उसे गलत handle करे।

API defect की कीमत उसके clients की संख्या से गुणा हो जाती है। Rename हुआ field या ख़राब input पर 500 web front end, partner integration और users के phones पर पहले से installed app versions को तोड़ सकता है, जबकि उनमें से किसी में कोई बदलाव नहीं हुआ। Conventions जानना "API कुछ अजीब लग रहा है" को test cases के लिए सटीक expectations में बदल देता है।

Resources, URIs, representations और statelessness

Fielding REST को छह constraints से परिभाषित करते हैं (जिनमें से एक optional है), जिनमें statelessness और uniform interface शामिल हैं। REST कहलाने वाले APIs अक्सर इन्हें आंशिक रूप से ही लागू करते हैं — client आगे क्या कर सकता है, यह बताने वाले hypermedia links अक्सर छोड़ दिए जाते हैं — इसलिए API को पहले उसके अपने contract से परखें और inconsistencies पकड़ने के लिए REST conventions इस्तेमाल करें। Testing के लिए चार ideas सबसे अहम हैं:

• Resource: API जो भी नाम वाली चीज़ दिखाता है — एक task, एक user, tasks की list। Resources संज्ञाएँ (nouns) हैं और action method से आता है: POST /tasks, न कि POST /createTask।
• URI: resource की पहचान, जिसका syntax RFC 3986 में परिभाषित है। एक आम convention है plural collection /tasks, उसके members /tasks/42 और sub-resources /tasks/42/comments।
• Representation: किसी ठोस format में resource की state। Client जो format भेजता है वह Content-Type में और जो formats पढ़ सकता है वे Accept में बताता है।
• Statelessness: हर request में वह सब होता है जो server को उसे समझने के लिए चाहिए — token जैसे credentials, identifiers, page number। Server पिछली requests का कोई session context नहीं रखता (stored resources ज़ाहिर है बने रहते हैं), इसलिए request दोहराई जाए, अकेले भेजी जाए या किसी दूसरे server पर handle हो, उसका मतलब वही रहता है। इसे ऐसे ही टेस्ट करें: pages 1 और 2 लाए बिना सीधे page 3 माँगें।

Methods की CRUD से mapping

CRUD — create, read, update, delete — stored data पर बुनियादी operations का नाम है। REST में हर operation एक HTTP method है जो collection पर या किसी एक item पर लगता है। Methods और उनकी safe व idempotent properties आप HTTP methods वाले lesson में देख चुके हैं; table उन्हें resources के साथ जोड़ती है।

Table के पीछे का pattern: create collection पर होता है और नए item का URI server चुनता है; read पूरे collection का या एक item का होता है; update और delete एक item पर, उसके अपने URI पर होते हैं। Table से बाहर के combinations — POST /tasks/42, या पूरे collection पर PUT, PATCH और DELETE — आमतौर पर उपलब्ध नहीं होते और उन्हें 405 Method Not Allowed मिलना चाहिए।

Operation  Method  URI          Typical success response
---------  ------  -----------  ---------------------------------------------
Create     POST    /tasks       201 Created + Location: /tasks/{id}
Read       GET     /tasks       200 OK, a list (often paged)
Read       GET     /tasks/{id}  200 OK, one task
Update     PUT     /tasks/{id}  200 OK or 204 No Content, whole task replaced
Update     PATCH   /tasks/{id}  200 OK or 204 No Content, sent fields only
Delete     DELETE  /tasks/{id}  204 No Content (200 with a body, 202 if queued)

REST API में status codes

Clients body पढ़ने से पहले status code के आधार पर आगे का रास्ता चुनते हैं, इसलिए code contract का हिस्सा है। REST में code operation और resource की state से तय होता है, इसलिए हर test case expected code बता सकता है।

• Create के बाद 201 Created, Location header के साथ जिसमें नया URI हो (RFC 9110)। सिर्फ़ body में id के साथ 200 एक आम विचलन है; यह defect है या नहीं, contract तय करता है।
• 204 No Content उस सफल update या delete के लिए जो कुछ नहीं लौटाता: body खाली होनी चाहिए।
• 404 Not Found गायब item के लिए, अभी-अभी delete हुआ item भी। खाली list खाली array के साथ 200 है।
• 405 Method Not Allowed ऐसे method के लिए जिसे resource support नहीं करता, Allow header के साथ जिसमें supported methods हों; RFC 9110 यह header ज़रूरी करता है।
• 415 Unsupported Media Type ऐसे body format के लिए जिसे resource स्वीकार नहीं करता; 406 Not Acceptable जब server Accept में दिया कोई भी format न बना सके — RFC 9110 उसे इसकी जगह अपना default format भेजने की छूट भी देता है।
• 409 Conflict जब request मौजूदा state से टकराए, जैसे पहले से registered e-mail; invalid input के लिए 400 या 422, एक जैसे इस्तेमाल के साथ।
• Client की गलती पर कभी 5xx नहीं: ख़राब input पर 500 का मतलब आमतौर पर यह है कि input validation या error handling गायब है।

आज़माएँ: HTTP स्टेटस एनालाइज़र आज़माएँ: HTTP स्टेटस कोड लुकअप

Worked example: एक task का पूरा lifecycle

Tester एक task को हर operation से गुज़ारता है और हर step के बाद status code और stored state assert करता है। Test account में शुरू में कोई task नहीं है।

• बाद के steps अंदाज़े वाले URI की बजाय Location header से मिला /v1/tasks/57 इस्तेमाल करते हैं।
• POST collection का method है: item /v1/tasks/57 पर उसे 405 मिलता है, और Allow बताता है कि item असल में कौन-से methods support करता है।
• DELETE के बाद item नहीं रहता, इसलिए GET /v1/tasks/57 404 लौटाता है; collection अब भी मौजूद है, इसलिए GET /v1/tasks खाली array के साथ 200 लौटाता है, 404 नहीं।
• हर method यहाँ भी अपने वादे निभाता है — PATCH सिर्फ़ भेजे गए fields बदलता है, PUT पूरी state लेकर आता है, और दोहराया गया DELETE 404 लौटाकर भी idempotent रहता है — जैसा HTTP methods वाले lesson के safe और idempotent methods तथा हर method में क्या टेस्ट करें वाले sections समझाते हैं।

POST /v1/tasks  {"title": "Pay rent", "done": false}
  -> 201 Created, Location: /v1/tasks/57
GET /v1/tasks/57
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": false}
PATCH /v1/tasks/57  {"done": true}
  -> 200 OK, {"id": 57, "title": "Pay rent", "done": true}
POST /v1/tasks/57
  -> 405 Method Not Allowed, Allow: GET, HEAD, PUT, PATCH, DELETE
DELETE /v1/tasks/57
  -> 204 No Content
GET /v1/tasks/57
  -> 404 Not Found
GET /v1/tasks
  -> 200 OK, []

आज़माएँ: REST API टेस्टर आज़माएँ: API रिक्वेस्ट बिल्डर

Versioning और breaking changes

API के ऐसे clients होते हैं जिन पर उसकी team का नियंत्रण नहीं, इसलिए उसे मनमर्ज़ी से नहीं बदला जा सकता। Breaking change वह है जो एक सही, बिना बदले client को fail कर दे: field हटाना या rename करना, उसका type बदलना, request के optional field को required बनाना, या URI या status code बदलना। नया endpoint या optional field जोड़ना आमतौर पर सुरक्षित है, बशर्ते clients अनजान fields को ignore करें।

REST कोई versioning scheme तय नहीं करता। Teams एक scheme चुनती हैं और उसे contract में, अक्सर OpenAPI document में, लिखती हैं: URI path (/v1/tasks), query parameter (?version=2), Api-Version: 2 जैसा custom request header (नाम हर API में अलग हो सकता है) या media type (Accept: application/vnd.example.v2+json)।

• नया version ship होने के बाद पुराने version के regression tests बिना बदले चलाएँ: v1 को अब भी अपने contract के मुताबिक़ व्यवहार करना चाहिए।
• एक ही request दोनों versions को भेजें और पक्का करें कि सिर्फ़ documented अंतर ही दिखें।
• बिना version, अनजान version और retired version वाली requests भेजें: documented default या साफ़ 4xx की उम्मीद करें, कभी 500 नहीं।

आज़माएँ: API रिस्पॉन्स कम्पेरेटर आज़माएँ: OpenAPI व्यूअर

अक्सर पूछे जाने वाले सवाल

संदर्भ

• RFC 9110: HTTP SemanticsIETF · 2022HTTP मेथड, हेडर फ़ील्ड, स्टेटस कोड और कंटेंट निगोशिएशन के अर्थ, वायर वर्ज़न से स्वतंत्र।
• RFC 3986: Uniform Resource Identifier (URI): Generic SyntaxIETF · 2005URI के भाग (स्कीम, अथॉरिटी, पाथ, क्वेरी, फ़्रैगमेंट), रिज़र्व्ड कैरेक्टर और परसेंट-एन्कोडिंग।
• RFC 5789: PATCH Method for HTTPIETF · 2010आंशिक अपडेट के लिए PATCH मेथड, जबकि PUT पूरे रिसोर्स को बदल देता है।
• OpenAPI SpecificationOpenAPI InitiativeREST API के वर्णन का मानक: पाथ, ऑपरेशन, पैरामीटर, स्कीमा, रिस्पॉन्स और सिक्योरिटी स्कीम।