5.615 min read

API Design Patterns & Best Practices

Understanding individual TMF APIs is necessary but not sufficient. The real challenge lies in how these APIs are composed, integrated, and operated at scale. This section covers the architectural patterns that make TMF Open API ecosystems work in practice -- event-driven architecture, notification patterns, channel integration, versioning, and the most common anti-patterns to avoid.

These patterns are not specific to any single API. They apply across the entire TMF API landscape and represent hard-won lessons from real telco integration programmes.

The APIs themselves are the easy part. The patterns you use to connect them determine whether your architecture scales or collapses.
— Common integration architecture observation

Event-Driven Architecture with TMF APIs

TM Forum Open APIs are designed for event-driven integration, not synchronous request/response chains. Every TMF API defines a set of events (create, state change, attribute change, delete) and a standard mechanism for delivering those events to interested subscribers.

Event-Driven Architecture (EDA)

In an event-driven architecture, systems communicate by producing and consuming events -- notifications that something has happened. Instead of System A calling System B to ask "has anything changed?", System B publishes an event whenever something changes, and all interested systems receive it automatically. This produces looser coupling, better scalability, and more resilient integrations.

TMF Event Types

Every TMF API defines a consistent set of event types for each managed resource. The pattern is predictable across all APIs:

Standard TMF Event Types

Event Pattern	Trigger	Example (TMF622)
{Resource}CreateEvent	A new resource is created	ProductOrderCreateEvent
{Resource}StateChangeEvent	The lifecycle state changes	ProductOrderStateChangeEvent
{Resource}AttributeValueChangeEvent	A non-state attribute is modified	ProductOrderAttributeValueChangeEvent
{Resource}DeleteEvent	A resource is deleted	ProductOrderDeleteEvent
{Resource}InformationRequiredEvent	Additional information is needed (some APIs)	ProductOrderInformationRequiredEvent

Each event contains the event metadata (eventId, eventTime, eventType) and the event payload -- a snapshot of the resource at the time of the event. This allows consumers to process the event without needing to call back to the source API.

The Hub/Listener Notification Pattern

The TMF Hub/Listener pattern is the standard mechanism for event delivery. It works like a publish-subscribe system where consumers register their interest and receive callbacks when events occur.

TMF Hub/Listener event notification pattern -- producers publish events, consumers receive callbacks

Figure 5.6 -- TMF Hub/Listener event notification pattern

How It Works

Hub/Listener Registration and Notification

Register Listener

Consumer -> Producer Hub

Consumer calls POST /hub on the producer API with a callback URL and query filter specifying which events to receive. Example: POST /hub with body { "callback": "https://som.example.com/listener", "query": "eventType=ProductOrderStateChangeEvent" }.

Hub Stores Registration

Producer Hub

The producer's hub stores the listener registration, including the callback URL and event filter. Multiple consumers can register independently.

Event Occurs

Producer System

Something changes in the producer system (e.g., a product order state transitions from InProgress to Completed).

Hub Matches Listeners

Producer Hub

The hub evaluates the event against all registered listener filters and identifies matching subscriptions.

Callback Delivered

Producer Hub -> Consumer Listener

The hub sends an HTTP POST to each matching listener's callback URL with the event payload. The listener processes the event asynchronously.

Hub Registration Best Practices

Always specify event type filters in your hub registration to avoid receiving irrelevant events. Use a dedicated listener endpoint per event type for cleaner processing logic. Implement idempotent event handling -- the hub may retry delivery on transient failures, so your listener must handle duplicate events gracefully. Consider implementing a dead-letter queue for events that fail processing.

Polling vs Push Patterns

While the hub/listener pattern provides push-based notifications, some scenarios still warrant polling. Understanding when to use each pattern is important for building efficient integrations.

Polling vs Push (Hub/Listener)

Aspect	Polling	Push (Hub/Listener)
How it works	Consumer periodically calls GET with filters	Producer pushes events to registered callbacks
Latency	Depends on polling interval (seconds to minutes)	Near real-time (milliseconds to seconds)
Network load	Constant, regardless of changes (wasteful when idle)	Proportional to actual changes (efficient)
Complexity	Simple to implement (just GET requests)	Requires listener endpoint, registration, error handling
Reliability	Consumer controls timing; missed polls can be caught up	Requires retry logic, dead-letter handling for failed deliveries
Coupling	Low -- consumer decides when to check	Medium -- consumer must expose a reachable endpoint
Best for	Batch processing, reporting, low-frequency checks	Real-time integration, order tracking, event chains

Use push (hub/listener) for: order state tracking, real-time inventory updates, alarm notifications, SLA violation alerts. Use polling for: nightly reporting, batch data synchronisation, systems that cannot expose callback endpoints (e.g., behind strict firewalls).

In practice, most telco architectures use a hybrid approach:

Hub/listener for real-time operational flows (order processing, alarm handling)
Polling for batch/reporting flows (daily inventory snapshots, monthly SLA reports)
A message broker (Kafka, RabbitMQ) as an intermediary that receives hub events and fans out to multiple consumers
Change Data Capture (CDC) for database-level synchronisation where APIs are not available

Many modern telco platforms replace direct hub/listener callbacks with an event streaming platform like Apache Kafka. The TMF API producer publishes events to Kafka topics instead of (or in addition to) calling listener URLs directly. This provides:

Durability -- events are persisted and can be replayed
Decoupling -- producers and consumers do not need to know about each other
Scalability -- consumers can be scaled independently via consumer groups
Replay -- new consumers can process historical events from the beginning
Ordering -- events for the same entity are delivered in order (within a partition)

The TMF event payload format remains the same; only the delivery mechanism changes from HTTP callback to Kafka topic.

Backend for Frontend (BFF) Pattern

TMF Open APIs are designed for system-to-system communication. They are not optimised for direct consumption by frontend applications (web, mobile, agent desktops). This is where the Backend for Frontend (BFF) pattern comes in.

Backend for Frontend (BFF)

A BFF is a thin API layer specifically designed for a particular frontend channel. It sits between the frontend application and the backend TMF APIs, providing: (1) API aggregation -- combining data from multiple TMF APIs into a single response. (2) Data shaping -- returning only the fields the frontend needs. (3) Channel-specific logic -- formatting data for the specific channel (web, mobile, agent). (4) Authentication -- handling frontend-specific auth patterns (OAuth, session tokens).

Intermediate

Why Not Call TMF APIs Directly from the Frontend?

TMF APIs are granular, resource-oriented APIs designed for system integration. A single customer view screen might require data from TMF632 (Party), TMF637 (Product Inventory), TMF621 (Trouble Tickets), and TMF622 (Orders). Making 4+ API calls from the frontend is slow and creates tight coupling.

Additional problems with direct frontend-to-TMF calls include: (1) Over-fetching -- TMF APIs return full resource representations when the frontend only needs a few fields. (2) Security -- exposing backend TMF API endpoints to the public internet creates attack surface. (3) Versioning -- TMF API version upgrades require frontend changes. (4) Performance -- mobile devices on slow connections cannot afford multiple sequential API calls. A BFF solves all of these by providing a channel-optimised API.

BFF Architecture

A Web BFF serves the browser-based customer portal or online shop. It provides:

Product browsing endpoint that aggregates TMF620 (catalog) with TMF637 (current products) to show "available for you" offerings
Customer dashboard endpoint that combines TMF632 (party), TMF637 (products), and TMF621 (open tickets) into a single response
Order submission endpoint that validates, enriches, and submits to TMF622
GraphQL or REST API optimised for web rendering patterns

One BFF Per Channel, Not One BFF for All

A common mistake is building a single "universal" BFF that serves all channels. This defeats the purpose: each channel has different data needs, performance requirements, and security constraints. Build one BFF per channel (web, mobile, agent, partner portal), each tailored to its channel's specific needs. The BFFs share the same backend TMF API calls but shape the responses differently.

API Versioning and Backward Compatibility

API versioning is a critical concern in telco environments where multiple systems evolve at different paces. TMF APIs follow semantic versioning (major.minor.patch) with specific compatibility rules.

TMF API Versioning Rules

Version Change	Compatibility	Examples
Patch (4.0.0 -> 4.0.1)	Fully backward compatible (bug fixes only)	Fix typo in description, clarify documentation
Minor (4.0.0 -> 4.1.0)	Backward compatible (additive changes only)	Add new optional attribute, add new endpoint, add new event type
Major (3.x -> 4.0.0)	Potentially breaking changes	Remove attributes, change data types, restructure resources

Versioning Strategies

TMF APIs include the major version in the URL path: /tmf-api/productCatalogManagement/v4/productOffering. When a major version changes, a new path is available alongside the old one, allowing consumers to migrate at their own pace.

In a real telco environment, you often need to support multiple API versions simultaneously. Strategies include:

Parallel deployment -- run both v3 and v4 endpoints, with a shared backend
API Gateway routing -- the gateway routes requests to the appropriate version based on the URL path
Version translation -- a mediation layer converts v3 requests to v4 internally
Sunset policy -- define clear timelines for deprecating old versions (e.g., 12 months after new version launch)

To ensure backward compatibility, implement consumer-driven contract testing. Each API consumer defines a contract specifying the fields, types, and behaviours it depends on. When the provider makes changes, these contracts are validated automatically:

Use tools like Pact or Spring Cloud Contract to define consumer contracts
Run contract tests as part of the provider's CI/CD pipeline
Any change that breaks a consumer contract is flagged before deployment
This catches breaking changes that version numbers alone might miss (e.g., changing the semantic meaning of a field)

API Gateway Patterns

An API Gateway is a critical infrastructure component in TMF API architectures. It sits between consumers and providers, handling cross-cutting concerns that would otherwise be duplicated in every API implementation.

Authentication and Authorisation -- validate API keys, OAuth tokens, and enforce access policies
Rate Limiting -- prevent any single consumer from overwhelming an API
Request Routing -- direct requests to the appropriate backend service or version
Protocol Translation -- convert between external protocols (HTTPS) and internal ones (gRPC, messaging)
Request/Response Transformation -- modify payloads for version compatibility or data enrichment
Monitoring and Analytics -- track API usage, latency, error rates, and generate reports
Circuit Breaking -- prevent cascading failures when backend services are down

API Gateway in a Telco BSS/OSS Stack

A telco API gateway might handle: (1) External channel traffic (customer web/mobile) routed to BFF services. (2) Internal API traffic between BSS and OSS systems routed to TMF API implementations. (3) Partner API traffic authenticated via separate API key sets with different rate limits. (4) Version routing -- /v3/productOrder goes to the legacy system, /v4/productOrder goes to the new system. (5) Monitoring -- all API calls are logged for audit, performance tracking, and billing (for partner APIs).

Common API Anti-Patterns

After years of TMF API adoption across the industry, several common anti-patterns have emerged. Recognising and avoiding these saves significant rework.

Anti-Pattern 1: The Chatty Integration

The Chatty Integration

Making dozens of fine-grained API calls to assemble a single business operation. Example: to display a customer view, making separate calls to TMF632 (get party), then TMF637 (list products), then for each product calling TMF638 (get services), then for each service calling TMF639 (get resources). This creates a waterfall of API calls with compounding latency. Solution: use a BFF or API composition layer to aggregate these into a single call.

Anti-Pattern 2: Ignoring Events

Ignoring Events (Poll Everything)

Using polling for all integration points instead of leveraging the hub/listener pattern. This wastes network bandwidth, increases latency, and creates unnecessary load on APIs. Polling every 5 seconds across 20 integration points means 240 API calls per minute with no changes. Solution: use hub/listener for real-time flows; reserve polling for batch/reporting only.

Anti-Pattern 3: Tight Coupling via Shared Data

Tight Coupling via Shared Database

Bypassing APIs and having systems read/write directly to each other's databases. This creates hidden dependencies, makes it impossible to replace components independently, and breaks when either system changes its schema. TMF APIs exist precisely to prevent this. Solution: all cross-system communication should go through APIs; each system owns its database privately.

Anti-Pattern 4: Over-Engineering the Event Model

Over-Engineering the Event Model

Creating custom event types beyond the standard TMF event patterns, or embedding complex business logic in event payloads. This creates a dependency on event consumers understanding proprietary event semantics. Solution: stick to the standard TMF event types. If you need complex event processing, do it in a dedicated event processing layer, not in the event model itself.

Anti-Pattern 5: No Idempotency

No Idempotency Handling

Failing to handle duplicate requests or events. In distributed systems, retries are inevitable. If a POST /productOrder is retried due to a network timeout, the system should not create two orders. Solution: use externalId for deduplication on creation requests, and implement idempotent event processing that checks whether an event has already been handled.

Anti-Pattern 6: Vendor-Specific API Extensions Everywhere

Excessive Vendor-Specific Extensions

Using vendor-proprietary API extensions for core functionality instead of the standard TMF attributes. This re-creates vendor lock-in despite using TMF APIs. Solution: use standard TMF attributes and characteristics for core data. Only use @type extensions for genuinely vendor-specific attributes that the standard does not cover. Document all extensions and plan for eventual standardisation.

API Security Patterns

TMF APIs carry sensitive telco data (customer information, network topology, service configurations). Security is non-negotiable.

API Security Layers

Layer	Mechanism	Purpose
Transport	TLS 1.2+ (HTTPS)	Encrypt data in transit
Authentication	OAuth 2.0, API Keys, mTLS	Verify caller identity
Authorisation	Role-based access control (RBAC), scopes	Control what each caller can access
Input Validation	Schema validation, input sanitisation	Prevent injection attacks and malformed data
Rate Limiting	Token bucket, sliding window	Prevent abuse and ensure fair usage
Audit Logging	Structured API access logs	Track who accessed what and when

Advanced

TM Forum Security Function (TMF630)

TMF630 provides guidelines and patterns for securing Open APIs, including OAuth 2.0 flows, token management, and consent handling. It is the foundation for securing any TMF API deployment.

TMF630 recommends OAuth 2.0 with the client_credentials grant for system-to-system communication and the authorization_code grant for user-facing flows. It defines standard scopes per API (e.g., productCatalog:read, productOrder:write) and provides patterns for consent management when customer data is shared with partners.

API Testing Patterns

Testing TMF API integrations requires a layered approach that covers conformance, contracts, integration, and end-to-end scenarios.

API Testing Layers

Test Type	What It Validates	Tools / Approach
Conformance Testing	API implementation matches the TMF specification	TMF Conformance Test Kit (CTK)
Contract Testing	API changes do not break existing consumers	Pact, Spring Cloud Contract
Integration Testing	Two systems communicate correctly via the API	Postman, REST Assured, custom test suites
End-to-End Testing	Full business flow works across all APIs	Cucumber/BDD scenarios covering Lead-to-Cash, Trouble-to-Resolve
Performance Testing	APIs meet latency and throughput requirements	JMeter, Gatling, k6
Chaos Testing	System handles failures gracefully (timeouts, errors)	Chaos Monkey, Gremlin, custom fault injection

API Observability

In a distributed TMF API architecture, observability is essential for understanding system behaviour, diagnosing issues, and ensuring service quality.

Distributed Tracing -- trace a single order request across TMF622 -> TMF641 -> TMF652 -> TMF640 to identify bottlenecks and failures (use OpenTelemetry or Jaeger)
Structured Logging -- correlate log entries across systems using a shared correlation ID passed as an HTTP header
Metrics -- track API latency (p50, p95, p99), error rates, and throughput per endpoint
Alerting -- set thresholds on key metrics (e.g., TMF622 error rate > 5% triggers PagerDuty alert)
API Dashboards -- visualise API health across the entire TMF API landscape in real-time

Correlation IDs Across the Order Chain

Pass a unique correlation ID (e.g., X-Correlation-ID header) through every API call in a business flow. When a product order (TMF622) generates a service order (TMF641), include the same correlation ID. This allows you to trace the entire fulfilment chain in your logging and monitoring tools, dramatically simplifying debugging.

Pattern Summary

When to Use Which Pattern

Pattern	Use When	Avoid When
Hub/Listener	Real-time event notification between systems	Batch processing, systems behind strict firewalls
Polling	Batch reports, low-frequency checks, firewall-restricted consumers	Real-time operational flows
BFF	Frontend applications need aggregated, shaped API data	System-to-system integration (use TMF APIs directly)
API Gateway	Cross-cutting concerns (auth, rate limiting, routing)	Simple point-to-point integrations in development
Event Streaming (Kafka)	High-volume events, replay requirements, multiple consumers	Simple integrations with 1-2 consumers
Contract Testing	Multiple teams independently developing consumers and providers	Single-team environments with full control

Section 5.6 Key Takeaways

TMF APIs are designed for event-driven integration, not synchronous request/response chains
The Hub/Listener pattern is the standard TMF mechanism for push notifications
Use BFF (Backend for Frontend) layers to serve channel-specific frontends -- never expose raw TMF APIs to end users
API versioning follows semantic versioning; run multiple versions in parallel during migration
Avoid the six common anti-patterns: chatty integration, ignoring events, shared databases, over-engineered events, no idempotency, excessive vendor extensions
API gateways handle cross-cutting concerns: auth, rate limiting, routing, monitoring
Observability (tracing, logging, metrics) is essential for operating distributed TMF API architectures
Use correlation IDs across the entire order chain for end-to-end traceability
Security is non-negotiable: TLS, OAuth 2.0, RBAC, input validation, and audit logging are baseline requirements