How To Treat an API As A Product.

Every company that sells something will know that there are tried and true ways to develop a great product. When this product isn’t tangible, though, it’s a little more challenging to apply a product mindset to its delivery. This is the case for companies that sell APIs – engineers must think of any API as a product if they want it to succeed in the market.

Sometimes, public APIs start life as an internal solution. Teams will spot a gap between systems and build a bridge between them by whipping up an API solution. Without building the API with a product mindset approach, the result can be a solution that is so badly documented and difficult to understand that even internally people don’t want to use it. Since APIs serve such a vast range of purposes across so many domains, this happens often – where a “quick fix” solution can turn into a nightmare in a short space of time.

API as a Product case study: AWS

Amazon Web Services is one of the best examples of a development team that avoided this nightmare. In the early 2000s they built a set of APIs for the use of AWS internally (for the Amazon store). They decided very early into this process that designing their APIs with a very strict code of conduct would benefit them in the future (little did they know just how much). Every software engineer had to collaborate via the API, ensuring that documentation was meticulous. They were thinking about development with a public consumer base in mind. So much so that when, a few years later, the company decided to launch AWS into the market, the development team was able to open the doors without redeveloping huge portions of their products. AWS’s multi-billion success speaks for itself when it comes to the importance of treating APIs as products.

How do API development teams start thinking like this? There are three main elements.

API Design

Documentation is the “show your working out in your Maths answer” of the API world. Engineers that are led by building systems that work in the here-and-now sometimes brush it under the rug as less than necessary. However, the engineers that come after them – and in this case, the customers using their API products – don’t think the same way.

An API isn’t tangible or visible. So visualising it with clear documentation is the only way for teams and customers to understand its exact inner workings. Imagine if programming languages were subjective to individual engineers, but everyone needed to work with the same codebase: it would be impossible to understand. Luckily, there are open API documentation standards available for teams to work with. You can find Swagger’s version of this here.

APIs should be simple and secure. This doesn’t mean all APIs must be a point-to-point transfer with no flexibility. Rather, for example, it means if the API handles data that must not be lost, the architecture should be designed to make deleting important data very difficult. Engineers who are familiar with microservices development practices can apply these methods to “API as a product” development –

Our client is building APIs that offer a specific set of purposes and can, if necessary, work independently of one another. The client is a market-leading ISV for financial advisors. The client made the decision to work with Godel on building an open-access solution via APIs – so that any third party wishing to integrate into Intelligent Office could ‘plug in’ to it. This would lead to autonomy for development being handed to the third party users, ultimately saving time and cost for the internal team. The Developer platform provides an extensive toolkit and documentation for the public APIs, providing users a simple way to build and ship applications.

System Thinking

The AWS example shows how important it is to plan the API’s architecture and stages of development well in advance (for them, it took 3 years of planning). Today’s platforms are complex and evolve quickly, with the rise of CI/CD leading to constant new deployments. Building connectivity between software that is not monolithic, but in a shifting microservices form, requires a mindset that is led by specificity and deep system understanding.

In a product context, when it comes to system thinking development teams must consider their target audience’s real needs before committing a line of code. Firstly – does the exact solution already exist in the market? If so, what are its flaws? Investing time and money in this line of thinking will ensure that the API at hand has a place on the market.

When development begins, the API architecture should be built with an approach led by agility; it must be possible to easily pivot features of the API. Not only does this ensure the API is sustainable as software evolves, but it helps the product weather the storm of unexpected market shifts.

As the API is released to the market, sadly glitches may occur when users don’t adhere to the exact scenarios imagined during the API development. This is not good and can be very expensive, so a good API monitoring system is necessary to minimise risk. Tools like AppDynamic, NewRelic, Prometheus, Datadog or Cloudwatch for AWS are some great options for this. It is an indirect form of customer feedback that informs us how to change architecture and design for the better. and design for the better.

Customer Focus

Engineers are the main customers of APIs. This is very valuable for companies that sell APIs; there are few enterprise-level cases where the manufacturer shares the same profile as the end user. Despite this, engineers must treat their counterparts as customers – a customer wants a product that is polished, simple and fully functional out of the box.

If the customer needs to work hard to understand the ins-and-outs of the product, and the product isn’t critical to their needs, it is likely they will move on and seek an alternative solution. Or, as engineers often do, they will hack away at the API and experience great frustration until it works. In both cases, the customer tends to suffer in silence. As the manufacturer, you should be aware of these issues as soon as they arise, and immediately be planning on fixing them.

Go to the user base and ask (politely) for their feedback. Some companies have public Slack channels for their API users (perfect for engineers) and others have feedback emails or web portals that encourage in-depth reviews and critiques. You can clearly see the parallels here with product-oriented platforms like TripAdvisor or Amazon’s star rating system, which show companies how to improve. User feedback is paramount to good product development.

Helping engineers have that perfect “out of the box” experience can be achieved in many more ways. Nobody wants to plug a product into their systems, only to find that it crashes the whole thing upon the first call request. Providing a “sandbox” as a safe environment for engineers to get used to the API is great to avoid this.

All in all, these are the product development factors that contribute to building a great API for customers. For further reading, I’d recommend the book Continuous API Management. This has some great core values for developing successful APIs.