Platform Engineering Guide: Golden Paths and APIs

Introduction

Platform engineering treats infrastructure capabilities as internal products. It is the discipline of designing and operating internal products that help software teams deliver and run applications with less repeated infrastructure work. A platform combines self-service interfaces, automation, standards, and shared capabilities into supported paths for common engineering tasks. The API Infrastructure Guide shows how these capabilities connect to API runtime and lifecycle operations.

The goal is not to hide all infrastructure or create a new ticket queue. A good platform reduces unnecessary cognitive load while preserving the context developers need to make safe decisions. It provides paved or golden paths for common use cases, allows deliberate escape hatches, and evolves from evidence about its users. This matters particularly for microservices and Kubernetes operations, where repeated infrastructure decisions can otherwise spread across every team.

This guide is for platform engineers, platform product managers, architects, engineering leaders, and API platform owners. It explains platform-as-a-product, team boundaries, internal developer platforms and portals, golden paths, API platform capabilities, governance, reliability, adoption metrics, anti-patterns, and maturity. Read it with the API Governance Guide and API Observability Guide when defining shared controls and operating feedback loops.

What Is Platform Engineering?

Platform engineering creates a reusable layer between application teams and the underlying infrastructure and operational systems. That layer may include:

Application and service templates.
Continuous delivery workflows.
Runtime environments and Kubernetes clusters.
API gateways, API management, and developer portals.
Identity, secrets, policy, and security controls.
Observability, SLO, and incident-management integrations.
Databases, messaging, caches, and other shared services.
Documentation, catalogs, scorecards, and support.

The platform exposes these capabilities through APIs, command-line tools, portals, configuration, and automated workflows. Platform engineering is not synonymous with buying an internal developer portal. A portal can be one interface to the platform, while the platform includes the underlying contracts, automation, and operating model.

The CNCF Platforms White Paper emphasizes treating a platform as a product whose success depends on the success of its users. That product mindset distinguishes a platform from a collection of centrally managed tools.

Platform as a Product

Internal developers are the platform's users. Product thinking means platform teams discover user problems, prioritize outcomes, ship coherent capabilities, measure adoption and satisfaction, and maintain a roadmap. The same product discipline applies when teams publish APIs through API management or a developer portal.

Start with User Journeys

Map common journeys such as creating a service, exposing an API, requesting a database, deploying to production, rotating a secret, investigating an incident, or deprecating an API. Identify waiting time, repeated decisions, policy friction, and failure points.

Define the Platform Promise

State which users and use cases the platform supports, what is self-service, what reliability it provides, and what remains the application team's responsibility. A narrow dependable platform is more useful than a broad catalog of partially supported tools.

Build the Thinnest Viable Platform

Start with the smallest set of capabilities that improves a real user journey. Reuse managed services and open source components where appropriate. Add abstraction only where it removes repeated complexity or enforces a valuable standard.

Operate a Feedback Loop

Use interviews, support requests, telemetry, adoption funnels, and delivery metrics. A platform is never finished; it changes with application architecture, security policy, infrastructure, and user needs.

Team Boundaries and Platform Interfaces

Clear responsibilities prevent the platform from becoming either an uncontrolled toolbox or a centralized operations bottleneck. Define the interface between application teams, platform teams, security, and operations, then encode repeatable decisions through API governance and supported workflows.

flowchart LR
  developers[Application and API Teams] --> interfaces[Platform Interfaces]
  interfaces --> workflows[Golden Paths and Automation]
  workflows --> capabilities[Runtime, API, Data, Security, and Observability]
  platform[Platform Team] --> interfaces
  platform --> workflows
  specialists[Security, SRE, and Governance Teams] --> policies[Standards and Policy]
  policies --> workflows
  capabilities --> feedback[Usage, Reliability, and Feedback]
  feedback --> platform

Application teams own their product behavior, domain decisions, service health, and production outcomes. Platform teams own the shared product, interfaces, automation, and reliability of platform capabilities. Security, SRE, and governance teams contribute requirements and reusable controls without manually reviewing every normal change.

Use explicit contracts:

Supported service types and environments.
Inputs and outputs of platform APIs and workflows.
Ownership and escalation paths.
Reliability and maintenance expectations.
Versioning, deprecation, and migration policy.
Escape hatches and criteria for unsupported use cases.

Internal Developer Platform vs Developer Portal

An internal developer platform (IDP) is the set of capabilities and workflows that enable teams to deliver software. An internal developer portal is a user interface for discovering services, documentation, ownership, templates, and actions. The portal may invoke platform APIs, but it is not the whole platform.

Concept	Primary role
Internal developer platform	Provides reusable delivery and operational capabilities
Developer portal	Presents discovery, documentation, ownership, and actions
Service catalog	Records services, APIs, owners, dependencies, and metadata
Platform API	Provides a stable programmable interface to platform capabilities
Golden path	Encodes an approved workflow for a common use case

Read API Catalog vs Developer Portal, API Developer Portal Guide, and Interactive API Documentation for related interfaces.

Golden Paths and Self-Service Workflows

A golden path is an opinionated, supported route through a common engineering task. It may include a template, pipeline, policy, runtime configuration, documentation, telemetry, and ownership metadata.

For example, an API service golden path might:

Create a repository from a maintained service template.
Register ownership and metadata in the catalog.
Configure build, tests, dependency scanning, and image publication.
Provision a runtime and deployment workflow.
Register routes and policy with the API gateway.
Configure identity, secrets, and authorization defaults.
Create metrics, logs, traces, dashboards, and SLO templates.
Publish API documentation to a developer portal.

flowchart LR
  request[Developer Requests API Service] --> template[Service and API Template]
  template --> pipeline[Build, Test, and Security Pipeline]
  pipeline --> runtime[Runtime and Gateway Configuration]
  runtime --> telemetry[Observability and SLO Baseline]
  telemetry --> catalog[Catalog, Docs, and Ownership]
  catalog --> operate[Team Operates the Service]

Golden paths should be easy to adopt and easy to understand. Avoid enforcing them solely through policy. Teams will bypass a path that does not meet their needs or makes failure difficult to debug. Provide escape hatches with clear ownership and support boundaries.

API Platform Capabilities

APIs are natural interfaces for a platform and also products that need platform support. An API platform can provide:

API design and contract standards.
Gateway routing, authentication, rate limiting, and traffic policy.
API lifecycle, version, and deprecation workflows.
Developer portal and catalog publication.
Consumer, credential, and subscription management.
Metrics, logs, traces, analytics, and SLO templates.
Multi-cluster and multi-environment configuration.
Policy-as-code and audit evidence.

The API Infrastructure Guide maps these capabilities. The API Management Guide covers lifecycle and platform operations, while the API Gateway Guide explains the runtime traffic layer.

Do not force all teams through one shared runtime instance. Standardize contracts, policy, and operations while allowing data planes and environments to match scale, locality, isolation, and regulatory requirements.

Governance Without Ticket Queues

Governance should define outcomes and encode repeatable controls. Manual approval may be appropriate for exceptional risk, but using tickets for every route, credential, or deployment makes the platform a bottleneck.

Use a layered model:

Standards: naming, documentation, ownership, versioning, security, and observability requirements.
Defaults: secure templates and preconfigured workflows.
Automated checks: API linting, policy validation, tests, admission controls, and deployment gates.
Runtime enforcement: gateway, identity, network, and data policies.
Evidence: inventory, audit events, telemetry, and compliance reports.
Exception process: time-bounded deviation with an owner and remediation plan.

The API Governance Guide explains federated ownership, policy lifecycle, and runtime enforcement in detail.

Reliability, Security, and Observability

The platform is on the critical path for many teams. Define SLOs for platform APIs, delivery workflows, runtimes, gateway control planes, portals, and other shared services. Design failure domains so one platform incident does not stop every application or request path. Use API security practices and API observability practices as part of that baseline.

Platform security includes human and workload identity, least privilege, secrets, software supply chain, tenant isolation, network policy, runtime API controls, and auditability. Provide secure defaults while keeping domain authorization with application teams. See the API Security Guide.

Observability should connect platform components, application services, deployments, and ownership. Offer standard instrumentation and dashboards, but allow teams to add domain signals. See the API Observability Guide.

Runbooks, incident roles, maintenance communication, upgrade plans, backup, and disaster recovery are product features. Reliability work should be visible on the platform roadmap.

Platform Adoption and Success Metrics

Measure value, not only platform activity.

Adoption and Experience

Percentage of target teams and services using supported paths.
Time from request to first successful deployment or API call.
Completion and abandonment by workflow step.
Developer satisfaction and recurring support themes.
Documentation success and self-service rate.

Delivery Outcomes

Lead time for changes.
Deployment frequency.
Change failure rate.
Time to restore service.
Time required to satisfy common security or governance controls.

Reliability and Efficiency

Platform SLO attainment and incident impact.
Application reliability for teams using supported paths.
Resource utilization and cost by capability.
Repeated manual work eliminated.
Upgrade and policy adoption time.

Avoid vanity metrics such as number of portal visits or templates created without evidence that delivery improved. Segment metrics by user journey and team maturity.

Platform Engineering Anti-Patterns

Build It and They Will Come

A platform designed without user research often automates the wrong workflow. Start with observed constraints and involve application teams in design and iteration.

Portal as the Platform

A polished catalog cannot compensate for unreliable automation, unclear ownership, or missing runtime capabilities. Build stable platform contracts first; use the portal to make them discoverable.

Ticket-Driven Self-Service

A form that creates a ticket is not self-service. Automate normal paths and reserve human review for exceptional decisions.

Maximum Abstraction

Hiding every infrastructure concept can make failures impossible to understand. Abstract repetitive mechanics while exposing ownership, state, constraints, and diagnostics.

One Path for Every Workload

Different workloads have different protocols, state, scale, isolation, and compliance needs. Support a small set of coherent paths rather than one universal template or unlimited customization.

Platform Team Owns Production for Everyone

If application teams hand off all operational responsibility, feedback slows and ownership blurs. The platform should enable teams to operate safely, not remove their accountability for service outcomes.

Platform Engineering Maturity

Platform maturity is not a fixed tool sequence. A practical progression is:

Fragmented: teams assemble infrastructure independently and rely on tickets.
Standardized: shared templates, environments, and baseline controls emerge.
Self-service: common workflows are available through stable interfaces and automation.
Product-managed: the platform has user research, roadmap, SLOs, and adoption metrics.
Ecosystem: multiple platform capabilities and teams share contracts, policy, and experience standards.

Advance when user outcomes justify it. A smaller product-managed platform can be more mature than a large portal with low trust and adoption.

Platform Engineering Best Practices

Treat internal developers as users and the platform as a product.
Start with high-friction user journeys and measurable outcomes.
Build the thinnest viable platform before expanding scope.
Define team responsibilities and supported contracts clearly.
Provide golden paths with transparent defaults and escape hatches.
Expose capabilities through APIs and automation, not only a portal.
Encode governance and security in normal workflows.
Design platform reliability, upgrades, and support as product features.
Measure adoption, delivery outcomes, reliability, and satisfaction.
Retire unused capabilities and iterate from evidence.

Platform Engineering Learning Paths

Platform and Governance

Developer Experience

Runtime and Operations

How API7 and Apache APISIX Fit

Apache APISIX can provide an open source API gateway data plane for a platform's runtime traffic controls. Its APIs and plugin model allow platform teams to integrate routing, authentication, traffic management, and telemetry into supported workflows.

API7 Enterprise adds centralized API lifecycle, gateway, cluster, and policy management. API7 Developer Portal provides API discovery, documentation, subscriptions, and consumer-facing workflows. Together these capabilities can form part of an API platform, but platform engineering also requires product management, team contracts, delivery automation, runtime environments, and operational ownership.

Adopt technology after defining the user journey and platform boundary. A platform succeeds when teams can deliver reliable software with less unnecessary coordination and clearer responsibility.