The Pillars of an API Product
In the book, Continuous API Management, authors Mehdi Medjaoui, Erik Wilde, Ronnie Mitra, Mike Amundsen introduces the notion of API product & the pillars supporting it!
When we think around APIs, there are 3 distinctive parts behind it -
- Interfaces — A manifest where a provider shares around his capabilities
- Implementations — The meat! It’s the piece which provides the realisation of the advertised capabilities.
- Instances — This represents the actual runtime!
To create API, one need to put time & effort into managing all of these 3 aspects and as product continually matures and changes, everything needs to be kept up-to-date!
The 10 pillars of the API product were laid out as a guidance to help understanding & managing all of these above complexities! Not all of these pillars carry the same amount of weight. Some pillars can be stronger than others, and one even decide that some pillars don’t need much investment at all.
The important thing is that the combined strength of these pillars raises your API, even as it evolves and changes over time!
The Pillars
1. API Strategy
API strategy pillar includes two key decision areas -
- Strategical aspect (The goal )— Why you want to build your API?
- Tactical aspect — How an API will help you to achieve that goal?
The strategical goal for the API product needs to bring value to the organisation owning it! One key thing to note here is the API strategy isn’t just for external facing APIs; it is also an important pillar for org’s internal APIs. The only real difference between internal API strategy and external API strategy is in the users they serve!
2. API Design
API Design pillar focuses around how the API Product that you are creating will look, feel, and be used! This has a big impact on the API Product as the interface is all that the consumers see when they want to use the API product. So, whatever interface design you come up has a big impact on the decisions you’ll make in the other pillars!
3. API Documentation
API Documentation pillar captures the work of creating an API learning experience. No matter how well the interface of an API is designed, consumers of it won’t be able to get started without a little help. So, it’s worth providing a good documentation. Its worth noting here is that a better developer experience, directly translates into a more strategic value for the organisation.
4. API Development
API Development pillar includes all of the decisions that is made to bring the APIs live. This is the meat around developing the API’s implementation in a way that stays true to its interface design.
While consumers of APIs really don’t care how one implement the APIs, development decisions do matter a lot, especially for the people who have to build, maintain, and change the API over its lifetime. If one choose technologies that are difficult to use, the API will be more difficult to maintain!
5. API Testing
API Testing pillar is all about the quality of the APIs. Here one need to make decisions about both what needs to be tested & how! This is no different from the typical quality assurance work one does in a software project.
6. API Deployment
API Deployment pillar includes all the work of moving the implementation of an API into an environment where the API consumers can start consuming it! The deployed API is called an instance, and one need to manage several of these instances to keep API running properly. The challenge of API deployment work is in making sure that all it’s instances behave consistently, remain available to its consumers & are easy to change when deemed necessary!
7. API Security
API Security pillar focuses on the decisions to accomplish the security goals to protect APIs from potential threats/attacks. The openness of APIs makes them a potential target and presents a new kind of attack surface. So, one need to spend time improving the security of their APIs.
8. API Monitoring
API Monitoring pillar focuses around accurately depicting the performance of an API & how it is being used. Lack of such visibility hinders proper management of API. The pillar of API monitoring is all about the work one need to do to make such information available, accessible, and useful.
9. API Discovery
API Discovery pillar is all about the work it takes to make APIs easier to find for your target consumers. This means helping consumers to easily understand what the API does, how it can help them, how they can get started, and how they can invoke it. Discovery is an important quality of API’s developer experience!
10. API Change Management
API change management pillar includes all the planning and management decisions one need to make when dealing with an API change. It’s a vitally important and complex domain. In general , the 3 goals for change management are choosing the best changes to make; implementing those changes as fast as possible & making those changes without breaking anything!
