API definition and implementation in Istio


Hello API Working Group and community!

(tldr; There’s a new API ingest proposal)

About a month ago, I submitted a proposal for supporting HTTP APIs in Istio. One of the thoughts in the proposal was based on the idea of ingesting an API specification that holds both:

  1. The shape of the API’s operations (via OpenAPI)
  2. The expression of the API for an authenticated request by extending the Open API to specify policy and routing.

This has, as anticipated, been controversial: While this denormalization was intended as a simplification and a way to avoid an overly-opinionated implementation, many folks have good reason to prefer the interface and implementation be clearly distinct. Less anticipated was the level of cognitive dissonance that the simplification caused, making it harder to communicate about how APIs would be supported by Istio and vendors. Overall, I feel the experiment was a net negative.

To address this, I’ve been working on an alternative method to express APIs that relies on the more traditional 1-m relationship between an API’s interface and the concrete expressions of the API (aka product, subscription, etc.). Besides a cleaner separation between client and server, the separation should also allow API definitions beyond Open API (such as gRPC) to be used with the interface-independent expression format.

The new proposal is now available for the Istio API Management Working Group for review. The base API document will also soon be updated to reflect the new thoughts. I appreciate your input!


1 Like