API#3: API Endpoints आणि Resources समजून घेणे

नमस्कार developers! 🙏

मागच्या दोन blogs मध्ये आपण API काय आहे आणि REST API कसे काम करते हे शिकलो. आज आपण खूप महत्वाच्या गोष्टी शिकणार आहोत - 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, DELETE, PUT) आधीच 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 📚

चला एक संपूर्ण bookstore API design करूया:

Books (पुस्तके)

GET    /books                  - सर्व books पाहा
GET    /books/5                - ID 5 चं book पाहा
POST   /books                  - नवीन book add करा
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 add करा

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 create करा
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
    → 40 वरून 20 books (41 ते 60)

Search (शोध)

GET /books?search=harry+potter
    → "Harry Potter" शोधा

GET /products?q=laptop&brand=dell
    → Dell चे laptops शोधा

---

व्यावहारिक उदाहरण - E-commerce API 🛒

Products Management

# सर्व products
GET /products

# Electronics category मधले products
GET /products?category=electronics

# ₹10,000 पेक्षा कमी किमतीचे, ratings नुसार sort
GET /products?price_max=10000&sort=-rating

# Search: "wireless headphones"
GET /products?search=wireless+headphones

# Page 2, प्रत्येक page वर 24 items
GET /products?page=2&limit=24

Shopping Cart

# User 50 ची cart पाहा
GET /users/50/cart

# Cart मध्ये product add करा
POST /users/50/cart
Body: {"product_id": 123, "quantity": 2}

# Cart मधील item update करा
PATCH /users/50/cart/item/5
Body: {"quantity": 3}

# Cart मधून item काढा
DELETE /users/50/cart/item/5

Orders

# Order create करा
POST /users/50/orders
Body: {
  "items": [...],
  "shipping_address": {...},
  "payment_method": "UPI"
}

# User चे सर्व orders
GET /users/50/orders

# Specific order
GET /users/50/orders/789

# Order ची status बदला
PATCH /orders/789
Body: {"status": "shipped"}

Versioning - API चे Version 🔢

जुने users ची apps break होऊ नयेत म्हणून API मध्ये 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 (Paths to resources)
✅ Plural वापरा (/books)
✅ Hierarchical structure (/authors/5/books)
✅ Query parameters filtering/sorting साठी
✅ Clean आणि consistent naming

आपल्या पुढच्या blog मध्ये आपण तुमचा पहिला API तयार करणार आहोत - actual code लिहून! 🚀

तोपर्यंत, खूप practice करा! 💪

---

आवडलं तर share करा 😊

Happy Coding! 💻✨