The istio/api repository serves as the central API definitions repository for the Istio service mesh platform. Written primarily in Go, it contains component-level APIs and common configuration formats specified using protobuf syntax. This repository is foundational to the Istio ecosystem, as it maintains strict independence by depending only on the istio/tools repository, while all other Istio repositories are permitted to depend on it. This architectural constraint ensures that api remains a stable, low-level dependency that does not create circular dependencies within the Istio project.
The repository enforces strict API governance through documented API guidelines that all contributors must follow when modifying protobuf definitions. When changes are made to proto files, contributors are required to regenerate corresponding artifacts including Go bindings, Python bindings, JSON schemas, and Kubernetes Custom Resource Definition files by running make gen. These generated files must be submitted as part of the same pull request as the proto changes, and the process also updates a proto.lock file to track modifications. This ensures consistency between source definitions and their generated representations across multiple languages and formats.
Backwards compatibility is a critical concern in this repository, enforced through buf breaking checks that automatically block pull requests attempting to introduce breaking changes. The buf.yaml configuration file allows maintainers to explicitly permit breaking changes when there are legitimate reasons to do so, or individual pull requests can be force-approved in one-off cases where breaking changes are necessary. This mechanism balances the need for API evolution with the stability requirements of downstream consumers.
The repository is classified across multiple domains reflecting Istio's comprehensive service mesh capabilities: service mesh, security, API gateway, proxy, networking, traffic management, cloud native, observability, policy enforcement, load balancing, and microservices. This breadth reflects that the API definitions cover not just basic networking but also security policies, observability configurations, and traffic management rules. The repository shares contributors with istio/istio, golang/go, and envoyproxy/gateway, indicating integration points with the main Istio implementation, the Go language ecosystem, and the Envoy Gateway project. As the authoritative source for Istio's API contracts, this repository is essential infrastructure for the entire Istio platform and its ecosystem of tools and extensions.
