Why maintain a one-to-one relationship between your OpenAPI Specifications, API proxies, and API products?

[jbryant]

In the Apigee Docs, it recommends "...that you maintain a one-to-one relationship between your OpenAPI Specifications, API proxies, and API products." Are we able to have some explanation as to why this is the recommendation, pros/cons of following this advice and situations when it should be dismissed? I'm interpreting it as: "An API proxy should be based on a single OpenAPI spec. That proxy should map to only 1 API product." Please let me know if this is an incorrect interpretation.

I'd like to create multiple products that use the same proxies but this recommendation gives me pause. Should I instead break down those products to implement the 1 to 1 proxy relationship and then bundle the products/proxies at the app level?

It seems kind of limiting but at the same time I don't want to disregard a recommendation.

[deboraelkin]

This recommendation is for keeping things simple, especially for people who are starting with Apigee.

There's nothing to stop you to have a product that includes multiple API proxies, or to include a given API proxy in multiple products.

This is effectively a many to many relationships and many customers make use of this flexibility. Eg: create different products for a given proxy with different attributes, such as different quota settings. Or include different, related API proxies in a single product to make it easy for developers to deal with them.

Just be aware though that when publishing a product into the Developer portal, you'll need to provide a single OpenAPI specification for all the endpoints in that product. So, if your product includes multiple API proxies, you'll need to create an OpenAPI spec that merges their individual specifications.