How to build an API programme that unlocks ecosystem value — from OpenAPI specification governance to developer portal adoption.
Enterprise APIs fail when they're treated as technical artefacts rather than products. An API without a clear consumer, versioning policy, and deprecation process is a liability disguised as an asset. API strategy succeeds when product thinking is applied from the first line of the specification.
This document consolidates lessons from eight API programme implementations, covering financial services open banking, retail omnichannel, and telecommunications BSS/OSS modernisation.
Author: CELESDEV Solutions — Integration & Data Practice.
Applicable contexts: Enterprises building internal or external APIs; open banking / PSD2 compliance programmes; organisations moving from point-to-point ESB integrations to API-first architecture.
Full document includes OpenAPI governance ruleset (Spectral), API product canvas template, gateway comparison matrix, and developer portal evaluation scorecard.
| PROTOCOL | BEST FOR | AVOID WHEN |
|---|---|---|
| REST | Browser, mobile, public APIs, CRUD resources | High-frequency internal calls (>1 k/s) |
| gRPC | Service mesh, streaming, low latency | Browser consumers without gRPC-web proxy |
| GraphQL | Flexible queries, BFF layer, portals | Simple CRUD, single consumer type |
| AsyncAPI | Event-driven, pub/sub, webhooks | Synchronous request-response patterns |
Selection rule: Start with the consumer context. Who calls this API, from where, and how often? Protocol follows consumer requirements, not architectural preference. Mixed-protocol estates are normal and should be governed consistently through the API gateway layer.
Governance principle: A single Spectral ruleset applied across all protocols ensures consistency in naming, versioning, error format, and security headers regardless of the underlying transport.
Most enterprises assessed at Level 1 or Level 2. Level 3 is achievable within 12 months with a dedicated API platform team. Level 4 requires a shift to product thinking across engineering leadership.