> For the complete documentation index, see [llms.txt](https://mominur.gitbook.io/mominur-notes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mominur.gitbook.io/mominur-notes/system-design/api/graphql.md).

# GraphQL

ধরো, তুমি এক রেস্টুরেন্টে গেছো। তুমি শুধু এক কাপ কফি আর এক টুকরো কেক চাইছো, কিন্তু ওয়েটার পুরো থালি এনে দিলো—ভাত, মাংস, ডাল, সব! REST API অনেকটা এমনই—তুমি যতটুকু চাও না কেন, ও পুরো resource পাঠায়।\
আর GraphQL বলছে: **তুমি ঠিক কী চাও, সেটাই বলো—আমি সেটুকুই দেবো।**

GraphQL হলো Facebook-এ জন্ম নেওয়া একটি query language, যা API communication-এ flexibility, efficiency আর Transparency  নিয়ে এসেছে।

***

### GraphQL কী?

**GraphQL** হলো API এর জন্য একটি **query language** এবং একটি **runtime**, যেটি client কে ডেটা ফরম্যাট কাস্টমাইজ করার ক্ষমতা দেয়। Client বলে, `আমি এই এই data চাই`—আর server ঠিক সেটুকুই পাঠায়।

#### মূল বৈশিষ্ট্য:

* Client নির্ধারণ করে কোন কোন ফিল্ড লাগবে
* একসাথে অনেক nested ডেটা আনা যায় (no overfetching)
* একবারের request-এ multiple resource ফেচ করা যায়
* REST এর মতো endpoint গাদা গাদা লাগে না—একটাই `/graphql`

***

### GraphQL Query Structure

GraphQL query অনেকটা JavaScript object এর মতো দেখতে:

```graphql
query {
  user(id: "101") {
    name
    email
    posts {
      title
      createdAt
    }
  }
}
```

**Response (JSON):**

```json
{
  "data": {
    "user": {
      "name": "Mominur",
      "email": "mominur@example.com",
      "posts": [
        {
          "title": "GraphQL শিখছি",
          "createdAt": "2025-04-19"
        }
      ]
    }
  }
}
```

> তুমি যা চাও, তা-ই পাবে — না এক ফিল্ড বেশি, না এক কম!

***

### GraphQL এর ৩টি প্রধান অংশ

#### 1️⃣ Query

Client যেটা চায়—ডেটা রিড করার জন্য।

#### 2️⃣ Mutation

Client যখন নতুন কিছু তৈরি বা আপডেট/ডিলিট করতে চায়।

```graphql
mutation {
  addPost(title: "নতুন পোষ্ট", content: "শুভেচ্ছা সবাইকে") {
    id
    title
  }
}
```

#### 3️⃣ Subscription

রিয়েলটাইম ডেটা দরকার? যেমন chat message, stock update ইত্যাদি।

```graphql
subscription {
  newMessage {
    content
    sender
  }
}
```

***

### বাস্তব উদাহরণ

#### Use Case: ইউনিভার্সিটি অ্যাপ

**REST দিয়ে `/students/101` এ গেলে যা আসতে পারে:**

```json
{
  "id": 101,
  "name": "Mominur",
  "email": "mominur@brur.com",
  "department": "CSE",
  "cgpa": 3.5,
  "address": {
    "city": "Dhaka",
    "zip": "1212"
  }
}
```

কিন্তু তুমি শুধু নাম আর CGPA চাচ্ছো। তাহলে REST-এ এটা ওভারফেচিং।

**GraphQL দিয়ে তুমি কেবল চাইতে পারো:**

```graphql
query {
  student(id: 101) {
    name
    cgpa
  }
}
```

***

### GraphQL vs REST

| বিষয়            | REST                        | GraphQL                           |
| --------------- | --------------------------- | --------------------------------- |
| Structure       | Fixed endpoints             | Single endpoint, dynamic queries  |
| Data fetching   | Overfetch/Underfetch সমস্যা | প্রয়োজনমতো ফিল্ড নির্বাচন করা যায় |
| Versioning      | API v1, v2 করতে হয়          | Schema পরিবর্তন করলেই যথেষ্ট      |
| Nested resource | Multiple requests লাগে      | একবারেই nested ডেটা আনা যায়       |
| Performance     | বেশিরভাগ ক্ষেত্রে ধীর       | অনেক দ্রুত, lightweight           |
| Documentation   | আলাদা করে লিখতে হয়          | Schema থেকে auto-generate হয়      |

***

### Security নিয়ে কিছু কথা

GraphQL এ security enforce করতে হয়:

* Query depth limiter (infinite nesting ঠেকাতে)
* Rate limiting
* Authentication (JWT, OAuth)
* Authorization (field-level access control)

***

### জনপ্রিয় GraphQL Tools ও লাইব্রেরি

| Platform   | Tool                                 |
| ---------- | ------------------------------------ |
| JavaScript | Apollo Server/Client                 |
| Node.js    | Express + graphql                    |
| Python     | Graphene                             |
| PHP        | Lighthouse                           |
| Mobile     | Relay (Facebook), Apollo iOS/Android |

***

### কখন ব্যবহার করবেন GraphQL?

🔹 তুমি যদি এমন API বানাও যেখানে:

* Frontend বিভিন্ন ধরনের ফিল্ড চায়
* Mobile-এ ব্যান্ডউইথ বাঁচাতে হয়
* Multiple resource একসাথে দরকার হয়
* Frequent changes আসবে

তবে GraphQL সেরা পছন্দ।

***

### কখন  REST বেটার হতে পারে?

* Simple বা ছোট-scale API
* Legacy system বা third-party integration
* Caching দরকার (REST easier to cache via HTTP)

***

### GraphQL মানেই Power to the Client

GraphQL আসলে **flexibility + performance + developer control** এর সুন্দর মিলন। REST একসময় রাজা ছিলো, কিন্তু এখন GraphQL তাকে যথাযথ টেক্কা দিচ্ছে।

> GraphQL gives clients the power to shape the data they need — no more, no less.

***

### GraphQL Schema কেমন দেখতে?

```graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post]
}

type Post {
  id: ID!
  title: String!
  content: String
}

type Query {
  user(id: ID!): User
}

type Mutation {
  addPost(title: String!, content: String): Post
}
```

***

GraphQL শিখলে তুমি শুধু আরেকটা API টুল শিখবে না—তুমি শিখবে ডেটা কিভাবে চাওয়া যায়, কিভাবে কাস্টমাইজ করা যায়, আর কিভাবে ডেভেলপার এক্সপেরিয়েন্স আরও উন্নত করা যায়। এটা শুধু টেকনোলজি না, এটা এক ধরনের mindset।