Non-Negotiables
These rules apply to every API regardless of team, domain, or delivery timeline. There are no exceptions. Violation blocks publication to any environment.
Contract-First Design
OpenAPI 3.0+ specification must be authored and peer-reviewed before any implementation begins. The contract is the single source of truth. Code is generated from or validated against it.
OAuth 2.0 / JWT Authentication
Every API endpoint requires authentication via OAuth 2.0 with JWT bearer tokens. Anonymous or API-key-only access is not permitted in production. Token validation occurs at the gateway layer.
TLS 1.2+ Enforced — No Plain HTTP
All API communication must be encrypted. TLS 1.2 is the floor; TLS 1.3 preferred. HTTP endpoints are blocked at the load balancer. Certificate management handled via automated rotation.
URL-Based API Versioning
Version segment is required in every API path: /api/v1/, /api/v2/. Consumers must explicitly opt into version changes. Unversioned paths are rejected at CI/CD.
Rate Limiting & Throttling Tiers
Every published API must declare throttling policy: requests-per-minute per subscription tier (Bronze, Silver, Gold, Platinum). Unlimited tier requires explicit architectural review and CTO sign-off.
Centralized Logging + X-Correlation-ID
All requests must propagate the X-Correlation-ID header end-to-end. Logs are shipped to the centralized SIEM. Absence of correlation tracing fails the API readiness review.
Security Scanning — OWASP Top 10
DAST/SAST scanning aligned with OWASP Top 10 is a mandatory CI/CD gate. Injection, broken auth, SSRF, and security misconfiguration checks must pass before any environment promotion. Zero critical findings to proceed.
SLA Definition Before Publish
Availability target (e.g., 99.9%), latency p95, and error rate threshold must be formally documented and agreed before API publication. SLA metrics feed directly into the Analytics dashboard and alerting rules.
Negotiables
These decisions are flexible and should be agreed upon within the team or API domain. Document your choices in the API contract or team runbook.
Naming Convention: snake_case vs camelCase
JSON field naming strategy is per team agreement. Recommended: align with the TM Forum schema convention used by your domain. Document the decision in the API spec's info.x-naming-convention extension.
Pagination: Offset vs Cursor-Based
Offset pagination is simpler to implement; cursor-based is recommended for large, time-ordered datasets. Choose based on collection size and consumer needs. Both patterns are acceptable with proper documentation.
Error Response Schema Detail Level
Minimum required: HTTP status code + machine-readable error code + human message. Additional fields (stack trace in dev, debug context, affected fields) are optional and environment-dependent.
SDK Auto-Generation
OpenAPI Generator or similar tooling to produce client SDKs (TypeScript, Java, Python) is strongly encouraged but not mandatory. High-traffic APIs with multiple consumer teams should prioritize this.
Mock-First vs Code-First Approach
Mock-first (Prism, WireMock, Mockoon) enables parallel consumer development before backend is ready. Code-first is acceptable for experienced teams with tight iteration cycles. Either approach is valid if contract-first is honored.
API Documentation Verbosity
OpenAPI descriptions, example payloads, and changelog notes are encouraged. Minimum threshold: every endpoint must have a summary, every parameter must be documented. Extended narrative documentation is optional.
Deployment Frequency & Release Strategy
Continuous delivery, release trains, or scheduled releases are all valid depending on domain. Recommended: align with ODA Component lifecycle cadence and notify API consumers via the Developer Portal changelog.
Sync vs Async — REST vs Event-Driven
REST/HTTP is default for request-response patterns. Event-driven (AsyncAPI + Kafka/AMQP) is preferred for state change notifications and high-volume telemetry. Use TMF688 Event Management for async notification hub patterns.
WSO2 API Manager — Governance Pillars
WSO2 API Manager provides the full API lifecycle management platform. Each component plays a distinct governance role in the publish-subscribe-enforce model.
Platform version: WSO2 API Manager 4.x on Kubernetes. All components are deployed as containerized workloads, managed via Helm charts, and integrated with the central identity provider (WSO2 IS) for federated authentication.
API Publisher
The design-time surface for API producers. Teams author OpenAPI specs, define lifecycle states (Created → Published → Deprecated → Retired), configure backend endpoints, and attach mediation policies. All API definitions are version-controlled and auditable.
Developer Portal
Self-service discovery and subscription hub for API consumers. Developers browse the catalog, read documentation, test endpoints via the built-in Try-It console, and subscribe using pre-approved application credentials. Reduces API onboarding friction.
API Gateway
The runtime enforcement point for all north-south traffic. Handles OAuth2 token validation, JWT claims extraction, throttling, request/response mediation, CORS, and correlation ID injection. Deployed as a cluster with horizontal autoscaling. Acts as the zero-trust perimeter.
Admin Portal
Operational governance console for platform administrators. Manage throttling tiers (Bronze/Silver/Gold/Platinum), configure subscription plans, set global policies, manage tenant workspaces, and approve developer applications. Policy enforcement starts here.
API Analytics
Real-time and historical usage dashboards powered by the analytics engine. Tracks request volumes, error rates by status code, latency percentiles (p50/p95/p99), top consumers, throttled requests, and SLA compliance. Feeds into alerting and capacity planning.
Key Manager
OAuth 2.0 authorization server and JWT issuance engine. Issues access tokens and refresh tokens, validates token signatures, maps scopes to permissions, and handles token introspection. Integrates with WSO2 Identity Server for enterprise SSO and LDAP/AD federation.
Traffic Manager
Distributed throttling decision engine. Maintains real-time counters for requests-per-unit-time across all gateway instances. Enforces hard and soft quota limits, communicates throttling decisions via JMS events to gateway nodes, preventing quota bypass in clustered deployments.
TM Forum APIs — Core Reference
TM Forum Open APIs define standardized REST interfaces for every major telco business domain. Adopting these specifications enables interoperability, reduces integration costs, and aligns with ODA Canvas component boundaries.
| TMF# | API Name | Domain / Use | Priority |
|---|---|---|---|
| TMF620 | Product Catalog Management | Define and manage product offerings, bundles, pricing rules, and product specifications for consumer and enterprise portfolios. | Core |
| TMF622 | Product Ordering | Manage the complete product order lifecycle — from order submission through validation, provisioning, and completion or cancellation. | Core |
| TMF629 | Customer Management | Customer profile CRUD operations, customer segmentation, account linking, and relationship management for residential and business customers. | Core |
| TMF632 | Party Management | Foundational identity entity: Individual, Organization, PartyRole, ContactMedium. The base from which Customer, Supplier, Partner, and Employee identities derive. | Foundational |
| TMF633 | Service Catalog | Manage service specifications, service templates, and service candidates that map to network and IT capabilities. | Core |
| TMF638 | Service Inventory | Track and query active service instances per customer. Provides real-time inventory of provisioned services across the customer base. | Core |
| TMF641 | Service Ordering | Orchestrate service delivery — from order receipt through fulfillment actions, resource assignment, and activation confirmation. Typically triggered by TMF622. | Core |
| TMF645 | Service Qualification | Check technical feasibility and availability before a customer proceeds with an order. Validates network readiness, coverage, and capacity at a given location or context. | Core |
| TMF648 | Quote Management | Generate and manage price quotes prior to order commitment. Supports complex B2B quoting workflows with validity periods and versioning. | Core |
| TMF652 | Resource Ordering | Provision physical and logical resources — IP addresses, ports, VLANs, physical equipment assignments — as part of service fulfillment. | Core |
| TMF654 | Appointment Management | Schedule and manage field technician visits, installation appointments, and customer-facing service windows. Coordinates with field workforce management systems. | Core |
| TMF666 | Account Management | Manage billing accounts, financial accounts, and associated payment methods. Links customer identities to billing relationships and account hierarchy. | Core |
| TMF674 | Geographic Address | Address validation, geocoding, and geographic reference management. Used during qualification, ordering, and field service scheduling to anchor services to verified locations. | Core |
| TMF676 | Payment Management | Process payments, handle refunds, and manage payment method registration. Integrates with payment gateways and billing systems for settlement workflows. | Core |
| TMF688 | Event Management / Notifications | Async event hub implementing publish-subscribe patterns. Enables decoupled, event-driven communication between ODA components. Powers notifications for order state changes, service events, and alarms. | Async Hub |
| TMF679 | Product Offering Qualification | Determine whether a specific product offering can be sold and delivered in a given geographic, technical, or contractual context before presenting it to the customer. | Core |
ODA Canvas — Open Digital Architecture
TM Forum's Open Digital Architecture (ODA) Canvas is the reference architecture for telco digital transformation. It defines how software components are structured, deployed, and governed at scale.
What is ODA? The Open Digital Architecture is TM Forum's blueprint for building composable, cloud-native telco platforms. It replaces monolithic BSS/OSS stacks with a canvas of interoperable, independently deployable ODA Components — each one owning a bounded business domain and exposing standardized TMF API interfaces.
Component-Based Microservices Canvas
Each ODA Component maps to a business capability (e.g., Product Catalog, Order Management). Components are independently deployable, versioned, and governed with clear ownership boundaries.
Standard TMF API Contracts per Component
Every component exposes its functionality through TM Forum Open APIs. The "exposed API" envelope defines exactly which TMF endpoints the component implements — creating sealed, interoperable interfaces.
Event-Driven Inter-Component Communication
Components communicate asynchronously via the ODA Event Hub (TMF688). No direct service-to-service coupling. This enables component replacement without cascading changes across the canvas.
Kubernetes-Native Canvas Runtime
The ODA Canvas runtime is built on Kubernetes using Custom Resource Definitions (CRDs) and Operator patterns. ODA Component manifests are deployed as Kubernetes CRs, managed by the Canvas Operator for lifecycle control.
Sealed/Exposed API Contract Boundaries
The distinction between "exposed" (outward-facing TMF APIs) and "dependent" (APIs this component consumes from others) creates an explicit API contract graph. Dependency mapping enables impact analysis and upgrade safety.
Vendor-Agnostic Composability
ODA components from different vendors can be assembled on the same canvas because they share TMF API contracts. Replace one vendor's Order Management with another's without breaking the surrounding ecosystem.
Observable by Design
The Canvas runtime embeds observability requirements into every component: structured logging, Prometheus metrics endpoints, and distributed tracing headers are mandated at the component specification level.
TM Forum Certification & Conformance
Components can be formally certified by TM Forum against the ODA specification. Certification covers API conformance, event schema compliance, and security posture. Reduces procurement risk significantly.
Party Management — TMF632
Party Management is the foundational identity domain. Before a customer can order, a supplier can deliver, or an employee can access — they must exist as a Party.
Core principle: A Party is any individual or organization that has a relationship with your business. TMF632 defines the canonical data model that every other domain — Customer, Supplier, Partner, Employee — extends or references. Get this wrong and every downstream integration breaks.
Key Entities
Why It's Critical
- Single source of identity across all BSS/OSS
- Prevents duplicate customer records in CRM
- Enables unified 360-degree customer view
- B2B partner onboarding starts with Party creation
- Role-based access control maps to PartyRole
Use Cases
- Unified customer identity across channels
- B2B partner lifecycle onboarding
- Internal org and employee management
- Regulatory KYC identity verification
- Data residency and GDPR subject mapping
Integration Touchpoints
- CRM (Salesforce, Siebel) — customer sync
- Billing system — account party linkage
- Order Management — requester/subscriber
- Identity Provider — party-to-user mapping
- Service Inventory — party-to-service binding
WSO2 Integration Pattern
- TMF632 exposed via WSO2 API Gateway
- JWT claims include partyId + partyRole scope
- Mediation policy enriches request context
- Rate limit tier derived from party segment
- Correlation ID maps to party audit trail
Sample PartyRole Scope Mapping
Service Mesh & Sidecar Pattern
The service mesh handles all service-to-service (east-west) communication concerns — security, observability, and reliability — without requiring changes to application code.
Service Mesh: A dedicated infrastructure layer that intercepts and manages all network traffic between microservices. Implemented via the sidecar pattern: an Envoy proxy is injected alongside each microservice pod, transparently handling all inbound and outbound traffic.
Istio as Control Plane: Istio manages the fleet of Envoy sidecar proxies. It distributes configuration, collects telemetry, enforces policies, and provides a unified API for traffic management rules — canary weights, circuit breaker thresholds, retry budgets.
mTLS — Zero-Trust Network
Mutual TLS between every service pair. No plaintext east-west traffic. Certificates are auto-rotated via Istio's certificate authority. Services authenticate each other cryptographically.
Circuit Breaking
Envoy-native circuit breaker opens automatically when upstream error rate or latency exceeds threshold. Prevents cascading failure across the service graph. Hystrix-compatible behavior without library dependency.
Retries with Exponential Backoff
Configurable retry policies per route: max attempts, retry conditions (5xx, connection reset), exponential jitter backoff. Idempotency awareness prevents unsafe retries on non-idempotent endpoints.
Distributed Tracing
OpenTelemetry-based trace propagation via Jaeger or Zipkin. Sidecar automatically captures span data for every hop. End-to-end request traces visible across all TMF API calls in a single order flow.
Traffic Shifting — Canary & A/B
Weight-based traffic splitting between service versions. Route 5% of traffic to v2, monitor error rates and latency, then progressively shift. No DNS changes, no load balancer configuration required.
Prometheus Metrics + Grafana
Envoy sidecar emits RED metrics (Rate, Errors, Duration) for every service automatically. Istio dashboards in Grafana provide service topology maps, latency heatmaps, and inter-service dependency graphs.
Non-negotiable threshold: Service mesh deployment becomes mandatory when your platform runs 5 or more microservices in production. At that scale, manual TLS management, per-service retry logic, and point-to-point observability are no longer operationally sustainable. The mesh pays for itself immediately in reduced incident MTTR.
Gateway vs Mesh — Boundary Clarity: The WSO2 API Gateway handles north-south traffic (external clients to internal services) — authentication, rate limiting, API versioning, and developer portal integration. The Service Mesh (Istio) handles east-west traffic (service to service) — mTLS, circuit breaking, and observability. These are complementary, not overlapping layers. The gateway terminates external TLS and injects JWT claims; the mesh re-establishes mTLS for the internal hop.
Architecture Reference Diagram
End-to-end request flow from external client through the API governance stack to ODA Canvas components.