API Style: REST, GraphQL, gRPC, WebSocket

API হলো দুইটা program এর মধ্যে কথা বলার চুক্তি। তোমার Flutter app আর backend এর মধ্যে, বা তোমার backend আর bKash এর payment gateway এর মধ্যে। চুক্তিটা কেমন হবে তার কয়েকটা জনপ্রিয় ধরন আছে: REST, GraphQL, gRPC, WebSocket, SSE, Webhook। প্রতিটা আলাদা সমস্যার জন্য ভালো। এই অধ্যায়ে দেখবো কোনটা কখন, আর ভালো API কীভাবে design করতে হয়।

#এক নজরে

#REST: সবচেয়ে প্রচলিত

REST এর মূল ধারণা: সব কিছু একটা resource (জিনিস), প্রতিটা resource এর একটা URL, আর HTTP method দিয়ে বলো কী করতে চাও।

#ভালো REST URL এর নিয়ম

✓ GET  /restaurants/15/menu-items
✓ POST /orders
✓ GET  /orders?status=pending&page=2&limit=20

✗ GET  /getAllOrders           ← URL এ ক্রিয়াপদ না, method ই ক্রিয়া
✗ POST /order/create           ← একবচন আর ক্রিয়াপদ
✗ GET  /orders/delete/42       ← GET দিয়ে কখনো কিছু বদলাবে না

• বহুবচন noun: /orders, /users
• ক্রিয়া নয়, method: কাজটা method দিয়ে বোঝাও
• Filter, sort, page query string এ: ?status=pending&sort=-created_at
• কিছু কাজ CRUD এ মেলে না: যেমন order বাতিল করা। তখন sub-resource বা action: POST /orders/42/cancel। এটা গ্রহণযোগ্য।

#Safe আর idempotent

এটা কেন জরুরি: mobile network দুর্বল হলে Flutter app request পাঠালো, server কাজ করলো, কিন্তু উত্তর ফেরার পথে network কেটে গেল। App জানে না কাজ হয়েছে কিনা, তাই আবার পাঠায়। PUT বা DELETE হলে সমস্যা নেই। কিন্তু POST /payments আবার গেলে দুইবার টাকা কাটবে। সমাধান হলো idempotency key: client প্রতিটা নতুন কাজের জন্য একটা unique id পাঠায়, server সেই id আগে দেখে থাকলে আবার কাজ না করে আগের ফলাফল ফেরত দেয়। বিস্তারিত Resilience আর Payment case study তে।

#Pagination

১০ লাখ order একসাথে পাঠানো যায় না। দুই রকম pagination:

Offset pagination: GET /orders?page=3&limit=20 → database এ LIMIT 20 OFFSET 40

• সহজ, "পেজ ৩" এ সরাসরি যাওয়া যায়
• সমস্যা: পেছনের পেজে গেলে ধীর (database কে আগের সব row গুনে বাদ দিতে হয়), আর মাঝে নতুন data এলে কিছু item দুইবার আসে বা বাদ পড়ে

Cursor pagination: GET /orders?limit=20&after=eyJpZCI6MTAyMH0

• Server শেষ item এর পরিচয় (cursor) দেয়, পরের request এ সেটা পাঠাও → database এ WHERE id < 1020 ORDER BY id DESC LIMIT 20
• দ্রুত, যত গভীরেই যাও, আর নতুন data এলেও ঠিক থাকে
• "পেজ ৩" এ সরাসরি যাওয়া যায় না

Flutter এর infinite scroll list (feed, order history) এর জন্য cursor pagination সবচেয়ে উপযুক্ত।

#Versioning

API একবার mobile app এ চলে গেলে বদলানো কঠিন, কারণ পুরনো version এর app অনেকের phone এ থেকে যায় (অনেকে মাসের পর মাস update করে না)। তাই:

• URL এ version: /v1/orders, /v2/orders (সবচেয়ে সহজ আর প্রচলিত)
• নতুন field যোগ করা নিরাপদ, পুরনো app সেটা উপেক্ষা করবে
• Field মুছে ফেলা বা নাম/type বদলানো মানে breaking change → নতুন version

#Error এর ধরন একরকম রাখো

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "আপনার account এ যথেষ্ট টাকা নেই",
    "details": {"needed": 55000, "available": 20000}
  }
}

Mobile app code দেখে সিদ্ধান্ত নেবে (কোন screen দেখাবে), আর message user কে দেখাবে। সব endpoint এ একই গঠন রাখলে app এর error handling এক জায়গায় লেখা যায়।

#GraphQL: client নিজে বলে কী চাই

REST এ order details screen এর জন্য হয়তো তিনটা call লাগে: /orders/42, /restaurants/15, /riders/7। আবার /orders/42 এমন ৩০টা field দেয় যার ৫টা লাগে। প্রথমটাকে বলে under-fetching, দ্বিতীয়টা over-fetching।

GraphQL এ একটা request এ ঠিক যা দরকার:

query {
  order(id: 42) {
    status
    total
    restaurant { name phone }
    rider { name location { lat lng } }
  }
}

সুবিধা: কম request, কম data (mobile data খরচ কমে), frontend team backend এর জন্য অপেক্ষা না করে নতুন screen বানাতে পারে।

অসুবিধা:

• HTTP caching কঠিন (সব request একটা endpoint এ POST)
• খারাপ query (অনেক গভীর nested) server কে ধসিয়ে দিতে পারে, তাই query এর জটিলতার সীমা লাগে
• N+1 সমস্যা: ২০টা order এর প্রতিটার restaurant আলাদা query তে আনলে ২১টা database query। DataLoader এর মতো কৌশল লাগে।
• শেখা আর চালানো REST এর চেয়ে জটিল

কখন: অনেক রকম client (web, mobile, admin) আর অনেক রকম screen, যাদের data এর চাহিদা আলাদা। ছোট team আর সাধারণ app এ REST ই যথেষ্ট।

#gRPC: server থেকে server

gRPC তে আগে একটা .proto file এ চুক্তি লেখা হয়:

service PaymentService {
  rpc Charge(ChargeRequest) returns (ChargeResponse);
}

message ChargeRequest {
  string order_id = 1;
  int64 amount_paisa = 2;
}

এখান থেকে Python, Go, Java সব ভাষার জন্য code তৈরি হয়। Data যায় binary তে (JSON এর চেয়ে ছোট আর দ্রুত), HTTP/2 এর উপর।

কখন: Microservice গুলোর নিজেদের মধ্যে কথা, যেখানে গতি জরুরি আর দুই পক্ষই তোমার নিয়ন্ত্রণে। Browser সরাসরি gRPC বলতে পারে না, তাই public API বা web app এর জন্য সাধারণত REST।

#Real-time: WebSocket, SSE, polling

Order এর status বদলালে user কে কীভাবে জানাবে? চারটা উপায়:

কোনটা বেছে নেবে:

• Server শুধু খবর পাঠাবে (order status, live score, AI এর লেখা) → SSE
• দুই দিকেই ঘন ঘন কথা (chat, game, rider এর location পাঠানো আর পাওয়া) → WebSocket
• কয়েক মিনিটে একবার update হলেই চলে → polling যথেষ্ট, জটিলতা নিও না
• App বন্ধ থাকলেও খবর দিতে হবে → এগুলোর কোনোটাই না, push notification (FCM/APNs)। Mobile OS background এ app এর connection বন্ধ করে দেয়।

#Webhook: "আমি তোমাকে জানাবো"

Payment gateway তে user টাকা দিলো। তোমার server কীভাবে জানবে? বারবার জিজ্ঞেস করার (polling) বদলে gateway নিজে তোমার একটা URL এ POST করে:

POST https://api.yourshop.com/webhooks/payment
X-Signature: sha256=8f3a...

{"event": "payment.succeeded", "order_id": "ORD-1042", "amount": 55000, "txn_id": "TX9F2K"}

Webhook নেওয়ার নিয়ম:

1. Signature যাচাই করো। যে কেউ তোমার URL এ নকল "payment সফল" পাঠাতে পারে। Gateway একটা গোপন key দিয়ে sign করে, তুমি মিলিয়ে দেখো।
2. একই webhook দুইবার আসতে পারে। Gateway নিশ্চিত না হলে আবার পাঠায়। txn_id দেখে আগে সামলানো হয়ে থাকলে আবার কিছু করো না (idempotent)।
3. দ্রুত 200 দাও, ভারী কাজ পরে। Webhook পেয়ে queue তে রেখে সাথে সাথে উত্তর দাও। না হলে gateway timeout ভেবে আবার পাঠাবে।
4. শুধু webhook এর উপর ভরসা না। মাঝে মাঝে webhook হারায়। একটা background job দিয়ে মাঝে মাঝে gateway কে জিজ্ঞেস করে মিলিয়ে নাও (reconciliation)।

#অনুশীলন

#নিজেকে যাচাই করো