What is the best practice in defining what goes into an apiproxy bundle?

[#1]

Does the community have an opinion what determines when a new bundle should be created as an API Program expands. We have one large bundle and see timeouts on deployments due to the size. We have been advised by support and Apigee Customer Success that the upper limit on size of the bundle is approximately 5 mb.

I am curious what criteria others are using to separate out resources into apiproxy bundles.

[#2]

Creating smaller, more granular apiproxy bundles, has many benefits for the API team. First, deployments are generally faster with smaller bundles meaning less time is spent waiting and more time is spent innovating and delivering value to your consumers! Second, you have the ability to more easily segment work between developers allowing a subset of APIs to be under development by a developer reducing the complexity of merge operations for instance. Smaller bundles are less susceptible to deployment errors such as timeouts. Finally, large deployments can lead to issues such as exhaustion of permgen space when multiple concurrent deployments occur.

Here are some guidelines that I find useful when thinking about this:

1. You must able to provide a base path that can be differentiated by Apigee to the resources that reside in a bundle. While not a logical construct is a technical requirement that Apigee be able to classify and route your request for processing. Base paths may contain wild cards meaning you could have something like /foo/*/bar as the base path. You don't have specify static terms for all components of the base path. The system works from most specific to least specific which allows for seeming "collisions" to be resolved intelligently by the message processor meaning a base path of /foo can be appropriately distinguished from /foo/*/bar.
2. Given that one of the benefits of bundles is the ability to isolate code, segment work, and reduce impact of deployments I like to combine combine common targets and functional areas into a single bundle. Consider that many API programs like to create a set of DevOps specific endpoints, providing the DevOps team to things like cache invalidation APIs, status APIs, etc. By putting these into a common bundle you can assure that a common security model is in place. So if you use OAuth to protect these endpoints with an external identity provider you don't have to provide complex Condition statements in your proxy preflow to enforce multiple security models as you would if you included these APIs in a single bundle.
3. Resources, resources, resources. Access to a common set of resources need to be in a common bundle if at all possible. If you have commerce related resources, say payment methods, that you are exposing then create a bundle for these resources distinct from you products endpoints. Again this allows you to focus on the distinct functional and security requirements of these endpoints without creating overly complex condition statements.

Breaking your API into a series of distinct apiproxy bundles doesn't come without some added complexity. For instance, your deployment strategy will need to taking into account multiple bundles rather than just one. Crafting the right base paths is a bit of an art - especially if you are refactoring away from a large monolithic bundle into many smaller bundles.

[#3]

One other criteria I use for api grouping and segmentation is the release schedule of the APIs. If certain APIs are being built by a group that manages their own release schedule, it is useful from mgmt prospective to group these APIs to enable releasing them together. Without this, it becomes difficult to control what gets released from each proxy bundle.

[#4]

One thing to note is finer grained proxies can create issues if you have uneven traffic across proxies and intend to use Spike Arrest polices which apply to a proxy, not across multiple proxies.