API Design Process

আধুনিক সফটওয়্যার ইকোসিস্টেমে ফ্রন্টএন্ড ক্লায়েন্ট (যেমন ওয়েব, মোবাইল বা IoT) এবং কোর ব্যাকএন্ড সিস্টেমের মাঝে নিরবচ্ছিন্ন, নির্ভরযোগ্য ও নিরাপদ ডেটা এক্সচেঞ্জের মেরুদণ্ড হলো API (Application Programming Interface)।

একটি ইন্ডাস্ট্রি-গ্রেড API শুধু রিকোয়েস্ট গ্রহণ আর ডেটা রিটার্ন করে না; বরং এটি সিস্টেমের হাই-থ্রুপুট, স্কেলেবিলিটি, ব্যাকওয়ার্ড কম্প্যাটিবিলিটি এবং সার্বিক ডেভেলপার এক্সপেরিয়েন্স (DX) নির্ধারণ করে। নিচে এন্টারপ্রাইজ লেভেলে API ডিজাইনের প্রতিটি ধাপ বিস্তারিত ও গভীরভাবে আলোচনা করা হলো।

ধাপ ১: রিকোয়ারমেন্টস অ্যানালাইসিস ও সিস্টেম বাউন্ডারি নির্ধারণ

API বাস্তবায়নের আগে ডোমেইন বাউন্ডারি এবং নন-ফাংশনাল রিকোয়ারমেন্টস পরিষ্কারভাবে চিহ্নিত করা আবশ্যক। আর্কিটেকচারে ত্রুটি থেকে গেলে পরবর্তীতে ডেটাবেজ স্কিমা এবং কন্ট্রাক্ট রিফ্যাক্টর করা অত্যন্ত জটিল হয়ে পড়ে।

• কনজিউমার প্রোফাইলিং: ফ্রন্টএন্ড ওয়েব, নেটিভ মোবাইল অ্যাপস, নাকি এক্সটার্নাল থার্ড-পার্টি পার্টনাররা এই API কনজিউম করবে?

• ডেটা কনসিস্টেন্সি ও ভলিউম: ট্রানজ্যাকশনাল ACID গ্যারান্টি প্রয়োজন, নাকি Eventual Consistency গ্রহণযোগ্য? পে-লোড সাইজ কেমন হবে?

• SLA ও পারফরম্যান্স গোল: রিকোয়েস্ট প্রতি p95/p99 লেটেন্সি বাজেট (যেমন: <100ms) এবং টার্গেট থ্রুপুট (RPS) স্পষ্ট করা।

• API-First Design Methodology: কোড লেখার আগেই OpenAPI (OAS 3.0+) স্পেসিফিকেশন লিখে ক্লায়েন্ট ও ব্যাকএন্ড টিমের মাঝে কন্ট্রাক্ট লক করে নেওয়া।

ধাপ ২: API আর্কিটেকচারাল স্টাইল নির্বাচন

প্রজেক্টের রিকোয়ারমেন্ট ও ডেটা প্যাটার্নের ওপর নির্ভর করে সঠিক আর্কিটেকচার নির্বাচন করতে হয়।

• REST (Representational State Transfer): রিসোর্স-ওরিয়েন্টেড, ইউনিভার্সাল HTTP প্রোটোকল, ক্যাশিং ফ্রেন্ডলি এবং পাবলিক API বা স্ট্যান্ডার্ড CRUD অপারেশনের জন্য আদর্শ।

• GraphQL: ক্লায়েন্ট-ড্রিভেন কোয়েরি ল্যাঙ্গুয়েজ। মোবাইল অ্যাপ বা ড্যাশবোর্ডের মতো জায়গায় যেখানে এক স্ক্রিনে একাধিক ডোমেইনের ডেটা লাগে এবং Over-fetching ও Under-fetching রোধ করা জরুরি।

• gRPC (Protocol Buffers over HTTP/2): ইন্টারনাল মাইক্রোসার্ভিস-টু-মাইক্রোসার্ভিস লো-লেটেন্সি ইন্টার-প্রসেস কমিউনিকেশন (IPC), বাইনারি সিরিয়ালাইজেশন এবং স্ট্রিমিংয়ের জন্য সর্বোত্তম।

• WebSockets / SSE (Server-Sent Events): রিয়েল-টাইম বাই-ডিরেকশনাল ইভেন্ট পুশিং (যেমন চ্যাট, স্টক প্রাইস, লাইভ ট্র্যাকিং)।

ধাপ ৩: প্রেডিক্টেবল ও রেস্টফুল রিসোর্স মডেলিং

এন্ডপয়েন্ট ডিজাইন সবসময় Nouns (রিসোর্স) কেন্দ্রিক হওয়া উচিত, কখনোই Verbs (ফাংশন) কেন্দ্রিক নয়। রিলেশনাল হায়ারার্কি বোঝাতে নেস্টেড পাথ ব্যবহার করা হয়।

স্ট্যান্ডার্ড এন্ডপয়েন্ট প্যাটার্ন

• GET /api/v1/users (ইউজারদের লিস্ট রিটার্ন করে — পেজিনেশন ফিল্টারিং সহ)

• POST /api/v1/users (নতুন ইউজার এন্টিটি তৈরি করে)

• GET /api/v1/users/{id} (নির্দিষ্ট ইউজারের ডেটা রিট্রিভ করে)

• PUT /api/v1/users/{id} (সম্পূর্ণ ইউজার অবজেক্ট রিপ্লেস করে)

• PATCH /api/v1/users/{id} (আংশিক ফিল্ড আপডেট করে)

• DELETE /api/v1/users/{id} (ইউজার রিসোর্স নিষ্ক্রিয় বা ডিলিট করে)

• GET /api/v1/users/{id}/orders (সাব-রিসোর্স এক্সেস: নির্দিষ্ট ইউজারের সব অর্ডার)

ধাপ ৪: ইউনিফায়েড রিকোয়েস্ট ও রেসপন্স খাম (Envelope Pattern)

এন্টারপ্রাইজ API-তে রেসপন্স ফরম্যাট সর্বদা একটি সুনির্দিষ্ট ও সামঞ্জস্যপূর্ণ স্ট্রাকচার বজায় রাখবে। এতে ক্লায়েন্ট সাইডে ডেটা ডিসিরিয়ালাইজেশন প্রেডিক্টেবল হয়।

সফল রেসপন্স স্ট্রাকচার (Python / Pydantic মডেল)

from datetime import datetime, timezone
from typing import Generic, Optional, TypeVar
from pydantic import BaseModel, Field

T = TypeVar("T")


class APIResponseEnvelope(BaseModel, Generic[T]):
    success: bool = True
    status_code: int = 200
    data: Optional[T] = None
    message: Optional[str] = "Operation completed successfully"
    timestamp: datetime = Field(
        default_factory=lambda: datetime.now(timezone.utc)
    )

Output

{
  "success": true,
  "status_code": 200,
  "data": {
    "user_id": "usr_99812",
    "name": "Farhan Ahmed",
    "email": "farhan@example.com"
  },
  "message": "User profile fetched successfully",
  "timestamp": "2026-10-05T01:32:00Z"
}

স্ট্যান্ডার্ডাইজড এরর রেসপন্স (RFC 7807 Problem Details Pattern)

{
  "type": "https://api.example.com/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "User with ID 'usr_99812' does not exist in the tenant database.",
  "instance": "/api/v1/users/usr_99812",
  "code": "USER_NOT_FOUND",
  "timestamp": "2026-10-05T01:32:00Z"
}

ধাপ ৫: ডিফেন্স-ইন-ডেপথ সিকিউরিটি: অথেনটিকেশন ও অথরাইজেশন

সিকিউরিটি কখনোই অপশনাল নয়। এন্টারপ্রাইজ সিস্টেমে অথেনটিকেশন (পরিচয় নির্ধারণ) এবং অথরাইজেশন (অনুমতি যাচাই) আলাদা লেয়ারে হ্যান্ডেল করা হয়।

• Authentication: স্ট্যাটলেস অ্যাক্সেসের জন্য ক্রিপ্টোগ্রাফিকালি সাইনড JWT (JSON Web Token) অথবা স্প্লিট টোকেন মেকানিজম (Short-lived Access Token + Rotating Refresh Token) এবং থার্ড-পার্টির জন্য OAuth 2.0 / OIDC।

• Authorization:

  • RBAC (Role-Based Access Control): রোল অনুযায়ী অ্যাক্সেস (e.g., ROLE_ADMIN, ROLE_CUSTOMER)।

  • ABAC (Attribute-Based Access Control): কনটেক্সট, রিসোর্স ওনারশিপ এবং আইপি/টাইম অ্যাট্রিবিউটের ওপর ভিত্তি করে অ্যাক্সেস কন্ট্রোল।

• জিরো ট্রাস্ট ও ডাটা এনক্রিপশন: ট্রানজিটে ডেটা সুরক্ষায় TLS 1.3 বাধ্যতামূলক এবং ডাটাবেজে কনফিডেনশিয়াল ফিল্ড এনক্রিপ্ট করে রাখা।

ধাপ ৬: স্ট্রিক্ট ইনপুট ভ্যালিডেশন ও স্যানিটাইজেশন

ক্লায়েন্ট থেকে আসা ডেটা কখনোই বিশ্বাস করা যাবে না। ভ্যালিডেশন বিজনেস লজিকে যাওয়ার আগেই কন্ট্রোলার বা রিকোয়েস্ট পাইপলাইনেই এক্সিকিউট হওয়া উচিত।

• টাইপ চেকিং ও বাউন্ডস এনফোর্সমেন্ট: স্ট্রিং লেন্থ, ইমেইল ফরম্যাট, রেঞ্জ এবং রেজেক্স রুল প্রয়োগ।

• ইঞ্জেকশন অ্যাটাক প্রতিরোধ: SQLi, NoSQLi ও XSS পেলোড ফিল্টার এবং প্যারামিটারাইজড কুয়েরি বাধ্যতামুলক করা।

ধাপ ৭: সিম্যান্টিক HTTP স্ট্যাটাস কোড ম্যাপিং

সঠিক HTTP স্ট্যাটাস কোড ক্লায়েন্ট অ্যাপ্লিকেশনকে রেসপন্সের ধরন ও পরবর্তী পদক্ষেপ তাৎক্ষণিকভাবে নির্ধারণ করতে সাহায্য করে।

ধাপ ৮: এন্টারপ্রাইজ API ভার্সনিং স্ট্র্যাটেজি

ব্রেকিং চেঞ্জ ছাড়াই সিস্টেমের বিবর্তন বজায় রাখতে ভার্সনিং অপরিহার্য।

• URI Path Versioning (সর্বাধিক ব্যবহৃত): /api/v1/orders থেকে /api/v2/orders। এটি রাউটিং, এপিআই গেটওয়ে ফিল্টারিং ও ক্যাশিংয়ের জন্য সবচেয়ে পরিষ্কার পদ্ধতি।

• Custom Request Header Versioning: X-API-Version: 2.0। ক্লিন URL স্ট্রাকচার ধরে রাখে।

• Content Negotiation / Media Type (Accept Header): Accept: application/vnd.company.v2+json (HATEOAS ও পিওর রেস্ট আর্কিটেকচারে বহুল ব্যবহৃত)।

• সানসেটিং পলিসি: পুরনো ভার্সন বন্ধ করার আগে রেসপন্স হেডারে Deprecation ও Sunset: <Date> হেডার যুক্ত করা।

ধাপ ৯: রেট লিমিটিং, কনকারেন্সি এবং ডিস্ট্রিবিউটেড ক্যাশিং

হাই-ট্র্যাফিক সিস্টেমে সার্ভার রিসোর্স প্রটেক্ট করা এবং সাব-মিলিমিলেসেকেন্ডে রেসপন্স রিটার্ন করার আর্কিটেকচারাল সমাধান:

• রেট লিমিটিং অ্যালগরিদম:

  • Token Bucket / Leaky Bucket: ট্র্যাফিক বার্স্ট নিয়ন্ত্রণে বহুল ব্যবহৃত।

  • Sliding Window Log: সুনির্দিষ্ট অ্যাকুরেসি দেয় এবং বাউন্ডারি স্পাইক প্রতিরোধ করে।

• ডিস্ট্রিবিউটেড ক্যাশিং (Redis / Memcached):

  • রিড-হেভি ডেটা মেমোরিতে রাখা যাতে ডাটাবেজ বটলনেক তৈরি না হয়।

  • Cache-Aside Pattern: অ্যাপ প্রথমে ক্যাশে চেক করে, মিস হলে ডাটাবেজ থেকে এনে ক্যাশ পপুলেট করে।

• HTTP ক্যাশিং হেডার্স: Cache-Control: public, max-age=3600, এবং ডেটা পরিবর্তন ট্র্যাক করতে ETag ও If-None-Match ভ্যালিডেশন।

ধাপ ১০: লিভিং ডকুমেন্টেশন ও স্পেসিফিকেশন

কোড এবং ডকুমেন্টেশনের অমিল দূর করতে কোড থেকে অটোমেটিক স্পেক জেনারেট করা আধুনিক নিয়ম।

• OpenAPI 3.0 / Swagger UI: কোডের মডেল এবং রাউটের সাথে ইন্টারঅ্যাক্টিভ ডকুমেন্টেশন স্বয়ংক্রিয়ভাবে সিঙ্ক রাখা।

• SDK Generation: OpenAPI স্পেক ফাইল (openapi.json) থেকে বিভিন্ন ভাষায় ক্লায়েন্ট SDK তৈরি করা (যেমন openapi-generator ব্যবহার করে TypeScript বা Swift ক্লায়েন্ট বানানো)।

• API Mocking: ফ্রন্টএন্ড টিম ব্যাকএন্ড কমপ্লিট হওয়ার আগেই মক সার্ভার দিয়ে ডেভেলপমেন্ট শুরু করতে পারে।

ধাপ ১১: টেক স্ট্যাক সিলেকশন ও আর্কিটেকচারাল ট্রেড-অফ

সঠিক টেক স্ট্যাক নির্বাচন নির্ভর করে সিস্টেমের I/O ও কনকারেন্সি প্যাটার্নের ওপর:

+-----------------------------------------------------------------------------------+
|                            API Architecture Decision                              |
+-----------------------------------------------------------------------------------+
                                         |
             +---------------------------+---------------------------+
             |                                                       |
      [ High Concurrency & I/O ]                              [ Complex Domain ]
      FastAPI / Go / Node.js                                  Spring Boot / Java
      - Async Event-Loop                                      - Enterprise Multi-tenant
      - Microservices                                         - Strong Type-Safety
      - Low Memory Footprint                                  - Rich ORM & ACID Transactions

1. Python (FastAPI): হাই-পারফরম্যান্স Asynchronous I/O, বিল্ট-ইন Pydantic ডেটা ভ্যালিডেশন এবং দ্রুত ডেভলপমেন্ট ভেলোসিটির জন্য চমৎকার।

2. Java (Spring Boot): এন্টারপ্রাইজ ব্যাংকিং, মাল্টি-টেন্যান্ট প্ল্যাটফর্ম, জটিল বিজনেস ডোমেইন (DDD) এবং হাই কনকারেন্সির জন্য বিশ্বস্ত।

3. Go (Gin/Fiber): এক্সট্রিম লো-লেটেন্সি ও আল্ট্রা-লাইটওয়েট মাইক্রোসার্ভিসের জন্য উপযুক্ত।

4. ডাটাবেজ ও পারসিস্টেন্স: রিলেশনাল ট্রানজ্যাকশনের জন্য PostgreSQL/MySQL; আনস্ট্রাকচার্ড ও ইভেন্ট স্টোরের জন্য MongoDB/Cassandra; হাই-স্পিড ক্যাশিং ও সেশন ম্যানেজমেন্টের জন্য Redis।

একটি দীর্ঘস্থায়ী ও স্থিতিস্থাপক API তৈরি করতে কেবল ডেটা আদান-প্রদান নয়, বরং শুরু থেকেই ইউনিফর্ম ইন্টারফেস, ডিফেন্সিভ ভ্যালিডেশন, জিরো-ট্রাস্ট সিকিউরিটি এবং ক্লিয়ার ভার্সনিং এনফোর্স করা প্রয়োজন।