An emerging best practice in API circles is to treat APIs like products. Similar to any other company product, APIs should be viewed as critical business assets instead of limited to amorphous codebases. Combined within the context of business offerings and values, APIs can help realize their full value.
James Higginbotham, Executive API Consultant at LaunchAny, shares his tips for considering APIs as products and making the most out of them on our latest podcast episode. Here are his three main ways of treating APIs as products.
1. Adopt an Outside-In Perspective
"Stepping away and thinking about [APIs] from the outside-in will deliver a more pleasant experience and help people to integrate with your API easily." — James Higginbotham
Adopting an outside-in approach to designing APIs involves an obsession with the customer. According to James, it’s about putting yourself in the shoes of your client and understanding their needs and preferences in order to direct product strategy.
Focusing solely on the technology side is detrimental to the health of your API. You need to start by aligning with what’s needed in the marketplace rather than jumping into the code first.
Get an outside perspective and think more about the needs of your target users. For example, what API design style do your consumers prefer? Is it REST, GraphQL, or a blend of both?
If you build an API program without considering the needs of your target audience, it may not live to see the light of day.
2. Have a Team with a Product Mindset
"This is where the product thinking comes in. You really need a group that looks at the marketplace, looks at the business, its architecture, and goals; that big picture stuff." — James Higginbotham
Assemble a team with a product mindset to help you design and deliver APIs that drive business value. A team that treats your integration assets as products can assist the overall organization in creating a vision for the success of your API programs. They can look at the big picture and steer the API strategy roadmap in the right direction.
James says it’s important to have a dedicated team that understands how your APIs work and also understands the objectives of your organization. This team can have an outside-in perspective and discover the gaps in the marketplace. By centralizing knowledge on how APIs are designed, a more consistent, customer-centric developer experience can be made possible.
The team should also coordinate the development of the API and ensure that the organization’s vision is not lost. James emphasizes, “you need somebody to make sure that everything is coordinated—that as each area releases new capabilities into the API, we’re headed in the same direction, and we’re not just doing what looks fun or cool.”
"Being able to define vocabulary for a particular area, or unify around the API, will make [the program] a lot more consistent and easier for the developers that are going to be using that API because now you’re using the same term." — James Higginbotham
Get the vocabulary right when describing various aspects of your API program, according to James. Avoid using jargon and domain-specific terms. See things through your customers’ eyes and use relatable and consistent terminology—it’ll make your API easier to consume and enhance the developer experience.
You can also step outside and freshly look at the API documentation from the perspective of an outside user. If you spend time reviewing the API just like an actual user, you can discover flaws and inconsistencies in terminologies that were previously hidden.
You can also bring an external contractor or even a developer from another team, someone who has never seen your API, to run through it and pinpoint areas where descriptions are incoherent and difficult to grasp. This “advocate” can build a reference application that showcases how your API works. You can use their feedback, especially the inconsistencies they got along the way, to improve your API’s vocabulary.
3. Adopt New Tech Incrementally
"Is that a positive change or is that introducing more complexity, more challenges later? And if it’s a positive change, run with it, embrace it, do it. But if you’re not sure, slow down a little bit and see. Can we simplify this a little bit for everyone involved?" — James Higginbotham
Just like any other business product, APIs should continually evolve. This will ensure they address the emerging consumer needs as well as take advantage of new technologies.
However, James says you have to adopt new technology incrementally. Starting small, while getting those essentials in place—and iterating over them until they begin to make sense for everyone in the organization—can help avoid introducing unnecessary complexities into your API program.
For example, if you adopt the modern microservices architecture without preparing sufficiently to handle it, you could introduce unnecessary complexities in your codebase and complicate API governance. Why would you need to build several services, each with its own unique technology, when having a single monolith could easily solve your problem?
James affirms that the success of an API program depends on how well you incorporate eight core disciplines of building API programs, which he compares to an eight-point compass. These disciplines include:
- Strategy and culture
- Process and governance
- Portfolio and products
- Discovery and documentation
- Onboarding and adoption
- Design and delivery
- Management and analytics, and security and operations
We’ll address more of these core disciplines in future episodes and blog posts.
More so, if you include a product mindset in every discipline of the API lifecycle, the API will flourish and maximize its return on investment. Treating APIs as first-class components of your product portfolio, from their initial design to final deployment and management, will help you reap their full value.
Subscribe to the API Intersection podcast for more deep dives into building effective API programs.