The patterns we use to design APIs that serve as clean contracts between modules — covering versioning strategies, error standardization, and hypermedia controls.
In a modular system, APIs are not just technical interfaces — they are contracts between teams and between system components. A poorly designed API creates coupling. A well-designed API enables independent evolution.
Versioning Strategy
We use URL-based versioning (/v1/, /v2/) for external APIs consumed by clients we don't control, and header-based versioning for internal service-to-service communication. URL versioning is explicit and cacheable. Header versioning is cleaner for internal consumers.
Error Standardization
Every API in a modular system must return errors in a consistent structure. We use RFC 7807 Problem Details as our standard. Every error response includes: type (a URI identifying the error class), title (human-readable), status (HTTP code), detail (specific message), and instance (the request that caused it).
Consistent error shapes mean frontend developers write one error handling function, not dozens.
Pagination Patterns
Cursor-based pagination for any collection that grows unboundedly. Offset-based pagination only for small, stable collections where jumping to a specific page is a user requirement. Cursor pagination prevents the "page drift" problem that makes offset pagination unreliable on live data.
The BFF Pattern
For each client type (web, mobile, third-party), we create a Backend for Frontend (BFF) — a thin API gateway that aggregates and shapes data from internal services into the exact shape each client needs. This eliminates over-fetching, under-fetching, and the proliferation of client-specific logic in shared services.
Modulifyr Engineering Team
Birtamode, Jhapa, Nepal · modulifyr.com