Source Control - Api Proxies

[#1]

Hi,

I am working on a product which we envisage will have a few set of API proxies; such as,

GET / POST / PUT / DELETE /registrations

GET / POST / PUT / DELETE /flights

GET / POST / PUT / DELETE /airports

Together the above list of API proxies will make an API Product. I was of the opinion that I should have one repository mapped to this API product containing multiple folders with each representing one API proxy. Of course I will adhere to Gitflow workflow branching model but at the level of API product (mapped to Git repository).

However, when I read this article (https://community.apigee.com/articles/34868/source-control-for-api-proxy-development.html), its suggesting a completely different approach than what I am thinking. The article suggests;

1 repo = 1 API proxy

but I am thinking 1 repo = 1 API product (= multiple API proxies)

Not sure whats the best approach, any thoughts anyone?

Thanks in advance,

Sapan

[#2]

I would stick with the recommendation of a repo for each proxy. As your API program and number of consumers grow, you will want more flexibility in your product definitions. New use cases will likely come up where a consumer needs access to only one of the proxies in a product or a proxy will need to be accessed through multiple different products. Of course the repo structure won't prevent you from doing that, but it will be harder to maintain and know which proxy lives in which repo as your products evolve.

[#3]

Good points @Jessica Glissmann.

+

Deploy all APIproxies when a merge happens to the product repo, run tests which can take lot of time some times when compared to just deploying the APIproxy which has changed.

=> 2 products can have the same set of APIs

[#4]

I agree with @Jessica Glissmann. Single repo per API proxy works best.

Many developers have been this route, and it might seem counterintuitive at the beginning, however, the conclusion that I've experienced, and a few of my colleagues is that single repo per proxy strikes the right balance between a monolithic (single-repo-for-all-api proxies) vs. a microservice-oriented approach (one-repo-per-api proxy). IME, here are some of the reasons why:

• Centralizing code management in a single-repo-for-all-api proxies seems a more sensible solution at the beginning. However, it doesn't scale in the end. Source code management complexity is at stake. For instance, more master or production branches with multiple naming conventions will make it difficult to follow. e.g. master-API-proxy-a, master-api-proxy-b, dev-apiroxy-a, dev-apiproxy-b, test... you get the idea. Imagine trying to find in Github the right branch associated with your proxy. With a single repo, you stick to a single master, dev, test, feature branches, etc.
• Single repo per proxy promotes independent deployment with build tools chosen per APIs teams. Some teams like Maven, others Gradle, or Gulp or Grunt. Imposing a single build tool might seem more homogenous. However, your API teams decide what tools they're more productive with. Let them choose.
• Fear of merges, which drives developer anxiety and analysis paralysis. Imagine having a single repo to manage all your API proxies with 2000 branches trying to merge code from one branch to another. How would you feel about merging code in a repo with 30 vs. 2000 branches? Let alone visualizing that in a graph.
• CI Tooling detection of changes. Jenkins, Travis, CircleCI, etc. might be configured to trigger jobs when they detect changes in your repo. Should jobs of API A be triggered for changes that happened with API B? You want to isolate that stuff. With a single repo per API proxy, you don't need to worry about it.
• Easier migrations. You decide to move from Github to Gitlabs. A monolithic repo can be hundreds of GBs. Vs a few MBs.
• I'm sure there's more. I'm sure I'm missing other benefits here and perhaps some disadvantages. However, this is all based on my experience and what the opinion of what I learned from the open source community. Please chime in and let us know your thoughts. Regardless you're pro single repo or not.
• One disadvantage tough, but not so much. I always get this question; I want all my APIs treated as a single deployment unit. Hence they pick a single repo, obvious right. Not so fast, there are techniques with one-repo-per api-proxy to manage all your APIs as a single deployment. It is a common practice to leverage Git Submodule or Subtree. It's kinda Git repos embedded within other repos, but clean. With this technique, you get the best of both worlds. It's easier to go from repos per api proxy to monolithic than (or almost impossible) to go from monolithic to single api proxy.
• Take it to the extreme, API proxies can be composed of even multiple repos too to promote reusability. I'm not kidding. For instance, with Node.js APIs you can build your APIs with dependencies with other modules. This technique applies the Unix Principle, do one thing and do it well. You'll realize down the road that your APIs share cross-cutting functionality/concerns, e.g. Security, Validation filters, Testing frameworks, etc. By implementing these as separate repos you'll end up doing yourself a favor by promoting reusability. Creating a single repo tends to build a single mesh of everything that is hard to reuse.

My two cents. Hope it helps!

[#5]

Thanks @Jessica Glissmann, @Maruti Chand, @Diego Zuluaga for your thoughts on the subject.

I suppose I should have been a bit more clearer with my particular situation.

* The product whose capabilities I intend to expose via APIs is a reasonably mature product in terms of the features it offers with quite a few clients already in production using it. Hence the possibility of new use cases coming up is greatly reduced. Please also note that the backend APIs are already existent which we now intend to expose publicly via Apigee. Hence, most of the backend infrastructure is already in place.

* The set of APIs that this product will expose, we do not see them as individual APIs wherein a consumer might only want to integrate with one of the APIs and not with the others in the API suite for that product.

* There are not going to be different teams working on different API proxies but instead there will be one product team working on a set of API proxies all associated with that single product. Hence different teams preferring different ways of deploying API proxies too is not really applicable in my case.

* Your point about migration - well, as explained above it will have to all or nothing from one house to the other. So it does not really matter whether I have one repo to move versus 5 respos. Besides, I in no way expect the size of that a single repository (for multiple api proxies) growing in size by more than say 50-100 MB.

* 2000 feature branches - this is not even the volume of all the feature branches we have created in the last 2 years of this products development. And as the product has matured, for exposing its pre-existing capabilities via APIs is certainly not going to result in 1 team (of 4 developers) creating those many feature branches.

* I am staring at about 7-10 APIs to be exposed via Apigee. Building their proxy definitions, deploying (or redeploying) them to Apigee Edge through CI should not take more than 4-5 minutes. So even if a commit in one of the API proxies (single repo for all proxies) triggers the entire Api Proxy set to be built and deployed, I think I can live with that considering the gain in the simplicity of the branching model.

P.S. - Please also note that my entire team is completely new to Apigee. In such cases, my usual approach is to start simple and deal with complexities as we gain more understanding. With that background I was personally leaning towards a single repo for all Api proxies so that they remain closely tied to each other in a central place.

With the above additional info, any further thoughts will definitely be welcome.

[#6]

Points taken. Thanks for sharing. Apigee is completely agnostic to any decision you make in regards version control, so you can go single or multiple repos. However from Customer Success (Professional Services leg), we have opinions on this based on our experiences. My suggestion, give your approach a try, and keep it monitored to see when it's time to pivot. Have an awesome day!