API endpoint perfectly কাজ করেও badly designed হতে পারে।

আজকের request নেয়। আজকের response দেয়।

তারপর mobile client আসে, webhook retry করে, field optional হয়, list বড় হয়, second tenant role আসে।

Handler এখনো “কাজ করে।”

Contract আর করে না।

Boundary-তে validate

TypeScript type runtime-এ নেই।

Network input untrusted।

Validate করি:

• shape;
• allowed value;
• length আর limit;
• identifier;
• date আর time zone;
• business meaning;
• risky unknown key।

তারপর একবার normalize।

Phone, email, currency code বা empty string-এর multiple form থাকলে domain service বারবার ambiguity discover করবে না।

Identity-ও contract

Request body operation-এর owner decide করবে না।

Server verified identity থেকে actor আর tenant context derive করে, target resource check করে।

Decision protected operation-এর ভেতর। শুধু page guard বা hidden button-এ না।

প্রতি endpoint-এ:

• actor কে?
• কোন tenant/account?
• কোন resource?
• কোন role?
• এখন operation allowed?

Error caller-কে action নিতে সাহায্য করুক

“Something went wrong” API contract না।

Stable shape:

type ApiError = {
  error: {
    code:
      | "VALIDATION_FAILED"
      | "NOT_FOUND"
      | "CONFLICT"
      | "RATE_LIMITED"
      | "DEPENDENCY_UNAVAILABLE";
    message: string;
    fields?: Record<string, string>;
    requestId: string;
  };
};

Human message improve হতে পারে।

Code client behavior choose করতে দেয়।

Database detail, stack trace, secret বা অন্য tenant-এর resource existence leak করবেন না।

Retry-তে idempotency

Network ambiguousভাবে fail করে।

Client জানে না payment, order, email বা job accepted হয়েছে কি না।

Retry duplicate করলে endpoint fragile।

Retryable creation বা side effect-এ:

• idempotency key;
• unique operation constraint;
• persisted result replay;
• safe status transition;
• provider event ID;
• deduplicated job enqueue।

“Frontend button disable” idempotency না।

Timeout আর cancellation product behavior

External dependency stall করতে পারে।

Define:

• timeout;
• retry policy;
• backoff;
• cancellation;
• fallback;
• user-visible state;
• alert threshold।

সব error retry না।

Authentication, validation আর conflict-এর decision দরকার, same request না।

Pagination stable

সব record return করা একসময় fail করবে।

Offset simple, কিন্তু insert/delete-এ shift করতে পারে।

Explicit ordering আর opaque cursor থাকলে cursor pagination stable হতে পারে।

Define:

• deterministic sort;
• page limit;
• cursor/offset rule;
• filter;
• empty response;
• total count behavior;
• maximum cost।

Unbounded query public feature করবেন না।

Webhook hostile input + delivery semantics

Webhook endpoint-এ:

• দরকার হলে raw body signature verify;
• timestamp/replay protection;
• event deduplication;
• server truth থেকে tenant/provider mapping;
• fast acknowledgement;
• background processing;
• safe log;
• retry-aware state change।

Provider delivery অনেক সময় at least once।

Repetition expect করুন।

Compatibility policy

প্রতি field change-এ new version দরকার না।

Public contract-এর rule দরকার:

• optional field add;
• deprecate;
• enum change;
• default behavior change;
• endpoint remove;
• support window;
• migration communication।

সম্ভব হলে additive।

Break দরকার হলে explicit আর observable transition।

Function না, contract test

Coverage:

• valid request/response;
• malformed input;
• unauthenticated;
• unauthorized;
• cross-tenant;
• conflict/duplicate;
• dependency timeout;
• retry;
• pagination edge;
• webhook replay;
• compatibility fixture।

System যেখানে meet করে, contract সেখানে।

Test-ও সেখানে।

আমার rule

API correct path easy, incorrect path predictable, dangerous path difficult করবে।

Route আর controller-এর চেয়ে বেশি লাগে।

Caller depend করতে পারে—এমন boundary লাগে।

Tenant ownership-এর জন্য পড়ুন secure multi-tenant foundation। Production-এর জন্য release review checklist।

Growth-এ API client ভাঙলে এক request, response আর failure case পাঠান।