API#3: API Endpoints और Resources को समझना

नमस्कार Developers! 🙏

पिछले दो blogs में हमने API क्या है और REST API कैसे काम करता है, यह सीखा।
आज हम API की दो बेहद महत्वपूर्ण concepts सीखने वाले हैं – Endpoints और Resources!

---

Resource क्या होता है? 🎯

Resource का मतलब है आपके application के अंदर मौजूद कोई भी “चीज़” (thing) जिसे आप manage करना चाहते हैं।

उदाहरण:

• E-commerce App: Products, Users, Orders, Cart

• Social Media: Posts, Comments, Likes, Users, Photos

• School Management: Students, Teachers, Classes, Exams

• Library System: Books, Authors, Members, Loans

हर resource एक noun (संज्ञा) होता है – कोई वस्तु या अवधारणा।

Resource के प्रकार 📦

1. Collection (संग्रह):

/books - सभी books का collection
/students - सभी students का collection

2. Individual Resource (एकल संसाधन):

/books/5 - ID 5 की एक book
/students/101 - ID 101 का एक student

---

Endpoint क्या होता है? 🔗

Endpoint एक URL (Uniform Resource Locator) path होता है, जिसके जरिए आप API से संवाद करते हैं।
यह आपके resource का “पता” होता है।

मूल Structure:

https://api.example.com/v1/books
     |          |        |    |
  Protocol   Domain   Version Resource

आइए इसे विस्तार से समझते हैं! 👇

---

Endpoints Design करने की Best Practices 🏆

1. हमेशा Plural (बहुवचन) का उपयोग करें

गलत ❌:

/book
/student
/product

सही ✅:

/books
/students
/products

क्यों? क्योंकि collection में एक से अधिक items होते हैं।

---

2. Nouns का उपयोग करें, Verbs का नहीं

गलत ❌:

/getBooks
/createStudent
/deleteProduct
/updateUser

सही ✅:

GET /books
POST /students
DELETE /products/5
PUT /users/10

ध्यान रखें: HTTP Method (GET, POST, PUT, DELETE) पहले से ही action बताता है।

---

3. Hierarchical (श्रेणीबद्ध) Structure का उपयोग करें

अगर resources के बीच relationship हो तो:

/authors/5/books
       |     |
    Author  उस author की books

/students/101/grades
        |       |
    Student  उस student के grades

/posts/20/comments
     |      |
   Post  उस post के comments

---

4. Lowercase और Hyphens का उपयोग करें

गलत ❌:

/MyBooks
/user_profiles
/ProductCategories

सही ✅:

/my-books
/user-profiles
/product-categories

---

Complete उदाहरण – Online Bookstore 📚

आइए एक complete bookstore API design करते हैं:

Books (पुस्तकें)

GET    /books                  - सभी books देखें
GET    /books/5                - ID 5 की book देखें
POST   /books                  - नई book जोड़ें
PUT    /books/5                - Book 5 की पूरी जानकारी बदलें
PATCH  /books/5                - Book 5 की कुछ जानकारी बदलें
DELETE /books/5                - Book 5 delete करें

Authors (लेखक)

GET    /authors                - सभी authors
GET    /authors/10             - Author 10
GET    /authors/10/books       - Author 10 की सभी books
POST   /authors                - नया author जोड़ें

Categories (श्रेणियाँ)

GET    /categories             - सभी categories
GET    /categories/fiction/books - Fiction category की books

Users और Orders

GET    /users/25               - User 25 की profile
GET    /users/25/orders        - User 25 के सभी orders
POST   /users/25/orders        - नया order बनाएं
GET    /users/25/orders/100    - Order 100 की details

Reviews (समीक्षाएँ)

GET    /books/5/reviews        - Book 5 के सभी reviews
POST   /books/5/reviews        - Book 5 के लिए review लिखें
DELETE /books/5/reviews/50     - Review 50 delete करें

---

Query Parameters – Extra जानकारी 🔍

जब data को filter, sort या search करना हो, तब query parameters का उपयोग किया जाता है।

Filtering (फ़िल्टरिंग)

GET /books?author=Sane-Guruji
    → Sane Guruji की books

GET /books?price_min=200&price_max=500
    → ₹200 से ₹500 के बीच की books

GET /products?category=electronics&available=true
    → Available electronics

---

Sorting (क्रमबद्ध करना)

GET /books?sort=price
    → कीमत के अनुसार sort करें

GET /books?sort=-price
    → कीमत के अनुसार उल्टा sort (- मतलब descending)

GET /students?sort=name,class
    → नाम और class के अनुसार sort करें

---

Pagination (पृष्ठांकन)

अगर हजारों books हों, तो सभी एक साथ नहीं भेजते।

GET /books?page=1&limit=20
    → पहले page की 20 books

GET /books?offset=40&limit=20
    → 41 से 60 तक की books

---

Search (खोज)

GET /books?search=harry+potter
    → "Harry Potter" खोजें

GET /products?q=laptop&brand=dell
    → Dell के laptops खोजें

---

Practical उदाहरण – E-commerce API 🛒

Products Management

GET /products
GET /products?category=electronics
GET /products?price_max=10000&sort=-rating
GET /products?search=wireless+headphones
GET /products?page=2&limit=24

---

Shopping Cart

GET /users/50/cart

POST /users/50/cart
Body: {"product_id": 123, "quantity": 2}

PATCH /users/50/cart/item/5
Body: {"quantity": 3}

DELETE /users/50/cart/item/5

---

Orders

POST /users/50/orders
Body: {
  "items": [...],
  "shipping_address": {...},
  "payment_method": "UPI"
}

GET /users/50/orders
GET /users/50/orders/789

PATCH /orders/789
Body: {"status": "shipped"}

---

Versioning – API का Version 🔢

पुराने users की apps break न हों, इसके लिए versioning की जाती है।

URL में Version:

https://api.example.com/v1/books
https://api.example.com/v2/books

Header में Version:

GET /books
Headers: {
  "API-Version": "2.0"
}

---

Common Mistakes – इन गलतियों से बचें! ⚠️

यम: 2–3 levels से ज्यादा nesting से बचें।

---

Quick Reference – Endpoint Patterns 📋

---

निष्कर्ष 🎯

Endpoints और Resources ही REST API की foundation हैं।

याद रखें:
✅ Resources = Nouns (Books, Users, Products)
✅ Endpoints = URLs (Resources तक पहुँचने का रास्ता)
✅ Plural का उपयोग करें
✅ Hierarchical structure अपनाएँ
✅ Filtering / Sorting के लिए query parameters
✅ Clean और consistent naming रखें

---

अगले blog में हम अपना पहला API बनाएँगे – actual code के साथ! 🚀

तब तक खूब practice करें! 💪

अगर पसंद आया हो तो share करें 😊

Happy Coding! 💻✨