A practical guide to enterprise API architecture, security, ownership and lifecycle governance, covering gateways, identity, least privilege, versioning, observability and operational responsibility.
Process map
ConsumerApp / partner
service / user
service / user
GatewayRouting / policy
rate limit
rate limit
AuthenticateIdentity / token
service account
service account
AuthoriseScope / role
least privilege
least privilege
API / ServiceBusiness logic
validation
validation
BackendCore system
data / service
data / service
ObserveLogs / metrics
traces
traces
GovernVersion / owner
lifecycle
lifecycle
What an API does
- Provides a defined contract through which one system or service can request data or invoke a business capability from another.
- Creates a reusable boundary between consumers and backend systems, reducing the need for every consumer to understand internal implementation details.
- Can support synchronous request/response interactions, while asynchronous patterns such as events or queues may be more appropriate for long-running or loosely coupled processes.
Security fundamentals
- Authentication answers 'who or what is calling?'; authorisation answers 'what are they allowed to do?'.
- Use strong identities for users and services rather than shared credentials.
- Use OAuth 2.0 / OIDC or other fit-for-purpose identity patterns where appropriate rather than inventing custom token schemes.
- Encrypt traffic in transit with TLS.
- Validate inputs and reject unexpected data early.
- Apply least privilege to scopes, roles and backend permissions.
- Store secrets in managed secret stores rather than source code or configuration files.
- Use rate limiting/throttling and gateway policies to reduce abuse, accidental overload and denial-of-service risk.
- Minimise exposed data and avoid returning fields a consumer does not need.
Lifecycle and governance
- Name an API owner and define who is responsible for availability, defects, security and consumer communication.
- Version interfaces deliberately and establish a deprecation process so consumers are not broken without warning.
- Document the contract, expected errors, authentication method, limits and support path.
- Treat schema or behaviour changes as production changes with testing and release discipline.
- Maintain an inventory or catalogue so APIs do not become invisible dependencies.
- Monitor usage, latency, errors and unusual access patterns.
API gateway role
- Provides a common entry point for routing and policy enforcement.
- Can centralise authentication integration, rate limiting, request filtering, logging and other cross-cutting controls.
- Should not become an excuse to move all business logic into the gateway; business logic belongs in the appropriate service/application layer.
When not to use an API
- High-volume analytical movement may fit ETL/ELT or streaming better.
- Structured B2B document exchange may fit EDI better.
- Long-running asynchronous workflows may fit messaging/events better.
- Simple scheduled batch exchange may be adequately served by managed file transfer.
Key lessons
- An API becomes part of the organisation's attack surface and operational dependency.
- Authentication and authorisation are different controls and both matter.
- Versioning, monitoring and ownership are as important as endpoint design.
- The best integration pattern is determined by the business interaction, not by whether APIs are fashionable.