As the popularity of microservices architectures has increased, we began to think about an additional concept: API’s or application programming interfaces. While the explosion of Mobile and Single-Page Web Applications, as well as the popularity of connected devices and wearables has made API’s an increasingly important component of modern applications, they are in fact, nothing new. Operating systems and other programs have used API’s since the late 1990’s. However, given the rise of the importance of API’s it is critical for IT leaders and organizations to create a mature API strategy in order to support the business objectives of the organization.
API’s Are All About Services
At present, when we talk about APIs, we’re usually referring to interfaces or services accessible using the web, or at least the network. Consumers of API’s can come in different flavors. It might be an application on your office laptop or a device installed in an elevator on the other side of the planet. The API’s goal is to provide a means of communication between two parties: a client and a consumer. This provides integration mechanisms between applications and, at the same time, decoupling operations so applications can evolve easily.
We live in an increasingly connected world. Our phones are continually receiving data and, in many cases, sending data back to multiple services. Even now, in our own homes, it’s very likely that devices such as a dryer or TV are communicating with its manufacturers’ servers for statistics, updates, and other goals. You can also control your lights and doorbell through the use of applications and web services.
The Whole is Bigger Than the Sum of Its Parts
When creating services, it is easy to think of them as individual pieces. It’s straightforward. We usually employ architectural approaches that dictate having a single responsibility per service.
The problem is not writing a service for a specific application function, but emerges when (not if) they start growing in number to the hundreds or thousands and become challenging to manage. It’s like leaving your yard unattended for a few weeks. As the number of API’s grow, if there’s no strategy behind them, you begin to lose visibility. There’s no way to know if an operation is already covered by an existing service or if they are still in use. You may be supporting services that nobody is using anymore.
It is crucial to think of API’s as an ecosystem. You want all components in good harmony. A combination of multiple factors helps achieve a happy balance:
- Choosing the right level of granularity. When working with monolith architectures, all your business logic happens in the same place. As you begin to distribute business operations in services, the way they should interoperate changes. Make a service covering many areas and you’ll lose the benefits of decoupling. Make them too small, and the increased complexity will surpass the benefits.
- The proper set of technologies and protocols. It’s frequently cited that working with services allows you to use “the best technology for the problem”. But many times, having multiple languages may be problematic for an organization. You need to have people to manage them. This doesn’t mean that you should use a single technology, as this will make you rigid. You just need the right mix.
- The correct scale. The way your organization works or reacts to incidents when you have only a small set of API’s may not be efficient enough to support having multiple products or teams.
Focusing on these three factors will help you define a good service platform to support your business objectives.
A Proper Governance Model is Key to a Strong API Strategy
Part of the challenges of an API platform is defining the way decisions will be made. When decisions are all made in a centralized way, like by a head of engineering or an architect, the decision-maker ends up becoming a bottleneck, and the pace is slow. If decisions are all distributed (i.e., the team decides what’s best for all the cases), it may result in chaos. For example, when there are more programming languages than the organization can effectively handle.
Considerations for creating API’s vary per project, but some common ones are:
- Programming language (Should we choose Python over Java?)
- Protocols (i.e., gRPC vs. REST vs. SOAP)
- URL definition (/users vs. /userCollection)
- Versioning strategy (Should we add version in the URL or through a request header?)
A proper governance model defines a mixed approach for each consideration. There should be some decisions delegated to the team for the sake of agility, and others centralized to ensure compliance. The questions that you will need to answer are:
- What decisions do we need to make?
- Who should be making them?
- What is the impact of each?
This approach ensures that the people not making choices are not ignored. Participation ranges from proposing something to challenging it, depending on what’s best for your organization.
API Simplicity is Critical to Success
When creating services, we tend to forget that someone will use them. Sure, an application or client will be making the HTTP request, but a human needs to write that piece of code in the first place.
We need to ensure that our APIs are easy to use, so it is attractive for other developers to pay for it (in the case we’re monetizing by usage or through a subscription). If monetization is not the goal, then having an API that is easy to use removes the temptation of some employees to go around it or write their own.
Ensuring a good developer experience is also critical for the success of any API strategy.
Consider the following scenario:
Acme ERP has a fantastic software product that many companies are willing to pay to integrate with. Since they don’t have the bandwidth to do it, they offer a contract for anyone interested in being their exclusive integration provider in the US. It sounds like an excellent business opportunity for your company. When you begin to review Acme’s environment, you notice:
- No sandbox or test environment exists. If you want to test any integration, it will be in production.
- There is no documentation of operations, input parameters, supported data types, or protocols.
- When errors happen, you don’t get the full details of what went wrong.
Would you try to win the contract? Probably not. The risk outweighs the reward. Further, imagine you budgeted two hundred hours for an integration and something fails. Since the API doesn’t give you many details, the full project takes 30% more to complete. There goes any profit you had hoped to make.
Several components provide a good developer experience, such as:
- A developer portal, listing all the operations, parameters, and return types for the APIs.
- A sandbox to safely test any operation.
- Restriction to specific APIs depending on the consumer’s privileges.
- Proper semantics and enough (useful) details when reporting an error.
A Good API Strategy is Just Good Business
Developing a good API strategy will involve making decisions that support your business goals during the planning process. These decisions will include many technology choices, as well as choices around how decisions are made. Making the right decisions; those that fit the way an organization works, will mean the difference between success and failure. In the end, the goal of APIs is to support your business objectives. Investing in defining a good strategy will make a difference in achieving them by design or by luck. How do you get there? There is a wealth of case studies and documentation on defining a good API strategy. Educating yourself and your team by studying the success of others is always a good place to start. However, the easiest method may be engaging with an organization that provides API consulting services that have implemented many API strategies in the past. They will be able to provide the guidance and training required to get your API strategy off the ground in the most seamless way possible.