I was asked the other day about whether to go with a multiple repository approach or a single repository approach for their API governance effort. This is a question with no right answers, and people who will tell you are wrong no matter which way you choose. It is right there with the mono application vs microservices discussion. It depends on where you prefer your complexity, and how much you empathize with new business and engineering folks who get involved with API operations and have to get up to speed. Whether or not you choose to go with a mono or distributed repo approach to API governance will depend on your enterprise and how teams see the world.
I personally prefer my complexity distributed. I do this because I regularly forget how things work and prefer a small single repository with a README and issues to help me get back up to speed with minimal cognitive load. The more a repository contains the more I have to get up to speed on. This is why I empathize with new product and engineering folks who are staring down a repository and have to get up to speed on what is going on. A mono repository will have a lot more folders, files, and discussions occurring, where a distributed approach will likely have just a handful of artifacts, less discussion, and ideally an up to date README that shares everything you need to know. You may have to travel further, but the cognitive load is lighter with many repositories used to manage your API governance.
Beyond onboarding and cognitive load I recommend a distributed approach primarily due to work streams, and avoiding your mono repository from becoming a bottleneck. There are plenty of ways in which your API governance will be perceived and become a bottleneck, and providing separate repositories helps separate out work streams. I recommend organizing your API governance as a single GitHub, GitLab, or Bitbucket organization, with repositories representing each domain, line of business, or team. Focus on your repository strategy being about producing Apis and less about consuming APIs, catering to guiding and increasingly velocity for teams. Like microservices, your distributed API governance repository isn’t about small or large, it is about right-sizing it for what is needed for a particular slice of your operation.
Another reason I see people push back on many repositories is they just do not know how to use GitHub, GitLab, or Bitbucket. When you operate at a certain level repositories are just folders. When done well the search, API, and other bells and whistles that come with your Git platform will help you manage the sprawl. To me, a GitHub organization is just like a repository, you just have more options for managing folders, separating conversations and work streams, and being more precise in how you onboard and move folks through the governance of APIs. Doing things in a distributed multi-repo way always will take more planning and education than doing things in a mono repo. If teams are made aware of the plan, have contributed to the plan, and are properly educated on Git, and the structure of repositories, then multiple repos will be less confusing than having to wade through a single large repository.
You will be criticized no matter whether you go with a single or multiple repository approach for your API governance. It comes down to your enterprise culture, and how much of a plan you have in place, and how literate teams are on this plan and on Git. The structure of your enterprise, teams, and how business drives API delivery (or not), which define whether or not a single or multiple repositories will make sense. Start with a single repository, but have a plan in place for how the repository will be structured. You can also start carving off repositories if you encounter friction with teams, and you see certain APIs become a problem. You can repeat this over and over until you have the right mix of repositories, which you can stitch together using your organization page or other internal dashboard and landing page. Ideally you’ve done the hard work of domain-driven design and have talked to teams about which approach makes sense, but if you are like most enterprises, you just need to get started with a single repository and learn along the way-—knowing there will be mistakes.
