Resources और URLs

Path में संज्ञाएँ, method में क्रियाएँ

REST-शैली के API में URL resource (कोई चीज़) का नाम देता है और HTTP method बताता है कि उसके साथ क्या करना है। बहुवचन संज्ञाएँ (/orders, /orders/42), हाइफ़न से अलग छोटे अक्षरों के शब्द उपयोग करें, और स्वामित्व सचमुच हो तभी nesting (/orders/42/items), लगभग दो स्तर से गहरा नहीं। Paths में क्रियाओं (/getOrder, /createUser) से बचें। जो ऑपरेशन सरल CRUD नहीं हैं, उन्हें मनमाने RPC नाम की जगह उप-resource या घटना के रूप में मॉडल करें (POST /orders/42/cancellation, POST /payments/pay_1/refunds)। Identifiers अपारदर्शी और स्थिर रखें, उन्हें दोबारा कभी उपयोग न करें, और enumeration का जोखिम हो तो auto-increment संख्याएँ उजागर न करें।

अच्छा और ख़राब URL डिज़ाइन

क्रिया-भारी शैली की तुलना resource-उन्मुख डिज़ाइन से करें। दोनों स्तंभ एक-से काम करते हैं।

Poor                                  Better
GET  /getAllOrders                    GET    /orders
POST /createOrder                     POST   /orders
GET  /order?id=42                     GET    /orders/42
POST /deleteOrder/42                  DELETE /orders/42
POST /cancelOrder/42                  POST   /orders/42/cancellation
GET  /customers/42/orders/7/items/3/x flatten: GET /order-items/3

उबाऊ और एकरूप रहें

बहुवचन नामों, casing (JSON में snake_case या camelCase, दोनों नहीं), तारीख़ों (ISO 8601) और ids के लिए एक परिपाटी चुनें और हर जगह लागू करें। अनुमान-योग्यता चतुराई से बेहतर है।

त्वरित जाँच: कौन-सा URL resource-उन्मुख डिज़ाइन का पालन करता है?

• GET /orders/42
• GET /fetchOrderNumber42
• POST /doDeleteOrder
• GET /orders/getById?id=42