-
Notifications
You must be signed in to change notification settings - Fork 33
Why did we make an API for registering APIs?
An organization might reasonably start by building an organization-wide repository of API specs, but this will quickly run into limits that call for a database of API descriptions and metadata. But databases also have limitations: limited access controls, specialized calling conventions, and lack of high-level operations lead us to build an API for APIs, the Registry API.
Some organizations have started collecting API information in a master “specs” repository that contains all of their API specifications. This is valuable, but it only allows coarse-grained access - PRs can be made to change anything in the repository, so lots of validation is needed and merging these PRs can be challenging. Essentially this approach forces the team to manage a single large document (the repository) that describes all of its APIs. This can work for small teams, but as the quantity of APIs and associated information grows, it becomes challenging.
Another way to organize specs in repos is to have a separate git repository for each API. This requires a top-level directory of all of these spec repos - that’s either another repo or some kind of database, maybe a spreadsheet of links, and validation is still needed for all changes. (For example, specs should not be removed or changed for published versions of APIs).
Another problem with specs repos is that they only provide very detailed views. People often require summaries and cross-sections. This calls for analytics and reports, and these need to be stored somewhere.
Databases take API management to a new level. With structured schemas and access controls, databases allow specs to be supplemented with additional API details, and databases also allow teams to track APIs that don’t have specs! But which database to use? How to grant access? Many teams working with APIs won’t have expertise in the database technology you choose, and you might also have difficulty mapping the database access controls to the uses you want to support. You might also need higher-level operations than your database provides. You can solve all of these problems with an API.
APIs allow auth and fine-grained RBAC, and very importantly, API interface technologies are rapidly becoming common languages used across teams. Nearly everyone knows how to work with APIs, so your teams can quickly start building the API management applications that they need. With an API, you can also start adding operations that automate high level flows and operations that represent sets of changes that could include direct calls to testing and deployment.