HATEOAS ও API ডকুমেন্টেশন (OpenAPI/Swagger)

১ · HATEOAS — লিংকসহ রেসপন্স

একটি সাধারণ (non-HATEOAS) API রেসপন্স শুধু ডেটা ফেরত দেয়: {"id": 1, "status": "pending", "total": 1200}। ক্লায়েন্টকে তখন আগে থেকেই জানতে হয় এই অর্ডার বাতিল করতে কোন URL-এ, কোন মেথডে কল করতে হবে — এই তথ্য ক্লায়েন্টের কোডে হার্ডকোড করা থাকে। HATEOAS এই সমস্যার সমাধান করে: রেসপন্সেই একটি _links অংশ যুক্ত থাকে যা বলে দেয় এই মুহূর্তে এই রিসোর্সে কী কী কাজ সম্ভব এবং কোন URL/মেথডে — ক্লায়েন্টকে আর URL হার্ডকোড করতে হয় না, শুধু লিংক অনুসরণ করলেই চলে।

২ · অবস্থা অনুযায়ী লিংক গণনা করা

নিচের কোড সেলে attach_links() ফাংশন একটি অর্ডার dict নিয়ে তার status পরীক্ষা করে নির্ধারণ করে কোন কোন লিংক প্রাসঙ্গিক। pending অর্ডারে বাতিল (cancel) ও আপডেট (update) সম্ভব, কিন্তু shipped অর্ডারে সেগুলো আর সম্ভব নয় — বরং একটি ট্র্যাকিং (track) লিংক প্রাসঙ্গিক হয়ে ওঠে।

orders = {
    1: {"id": 1, "status": "pending", "total": 1200},
    2: {"id": 2, "status": "shipped", "total": 850},
}

def attach_links(order):
    """অর্ডারের বর্তমান অবস্থা দেখে প্রাসঙ্গিক হাইপারলিংক গণনা করে যুক্ত করে"""
    base = f"/orders/{order['id']}"
    links = {
        "self": {"href": base, "method": "GET"},
        "items": {"href": f"{base}/items", "method": "GET"},
    }

    if order["status"] == "pending":
        links["cancel"] = {"href": f"{base}/cancel", "method": "POST"}
        links["update"] = {"href": base, "method": "PATCH"}
    elif order["status"] == "shipped":
        links["track"] = {"href": f"{base}/tracking", "method": "GET"}

    order_with_links = dict(order)
    order_with_links["_links"] = links
    return order_with_links

order1 = attach_links(orders[1])
order2 = attach_links(orders[2])

print("== অর্ডার ১ (pending) ==")
print(order1)

print("\n== অর্ডার ২ (shipped) ==")
print(order2)

print("\n== যাচাই ==")
print(f"pending অর্ডারে 'cancel' লিংক আছে:      {'cancel' in order1['_links']}")
print(f"shipped অর্ডারে 'cancel' লিংক নেই:       {'cancel' not in order2['_links']}")
print(f"shipped অর্ডারে 'track' লিংক আছে:        {'track' in order2['_links']}")
print(f"pending অর্ডারে 'track' লিংক নেই:        {'track' not in order1['_links']}")
print(f"দুই অর্ডারেই 'self' ও 'items' লিংক আছে:  "
      f"{all(k in order1['_links'] for k in ('self', 'items')) and all(k in order2['_links'] for k in ('self', 'items'))}")

৩ · OpenAPI/Swagger — মেশিন-পাঠযোগ্য ডকুমেন্টেশন

OpenAPI (আগে Swagger নামে পরিচিত ছিল) একটি স্ট্যান্ডার্ড, YAML বা JSON ফরম্যাটে লেখা স্পেসিফিকেশন যা একটি API-র প্রতিটি endpoint, তার parameter, request body শেপ, এবং সম্ভাব্য response শেপ/status code বর্ণনা করে — মানুষের পড়ার জন্য প্রোজ ডকুমেন্টেশনের বদলে, এটি এমন একটি কাঠামোবদ্ধ ফাইল যা টুল দিয়ে পার্স করা যায়। এই একটি ফাইল থেকে স্বয়ংক্রিয়ভাবে তৈরি করা যায়:

• ইন্টারঅ্যাক্টিভ ডকুমেন্টেশন (Swagger UI) — ব্রাউজারে সরাসরি API টেস্ট করার UI
• ক্লায়েন্ট SDK — বিভিন্ন ভাষার জন্য টাইপ-সচেতন API ক্লায়েন্ট কোড
• রিকোয়েস্ট ভ্যালিডেশন — ইনকামিং রিকোয়েস্ট স্পেসিফিকেশনের সাথে না মিললে আগেভাগেই ধরা

এই পাঠের সুযোগের বাইরে বাস্তব OpenAPI YAML তৈরি করা, কিন্তু মূল ধারণাটি বোঝা জরুরি — HATEOAS রানটাইমে "এই মুহূর্তে কী করা যায়" জানায়, আর OpenAPI ডিজাইন-টাইমে/ডকুমেন্টেশনে "এই API সামগ্রিকভাবে কী কী করতে পারে" জানায় — দুটো ভিন্ন স্তরে একে অপরের পরিপূরক।