OCTOBER 29, 2019
8 min read
The process of mobile and web application development becomes more fluent with every passing year. The most significant changes and the most exciting solutions were brought by big companies that opened their API for external public access. For example, if we want users to have the possibility to buy goods in our application, we don’t need to develop our own payment and card processing systems. We can just integrate with Stripe’s API. If we want users to have the ability to send an SMS, we’ll use Twilio. With Slack’s API, we can make monitoring systems very easy: if the server-side has not been responding for a while, we will receive a notification in Slack. In the message, we can see the time of the last response and the name of the service that is not responding. Integrations simply make our lives easier.
I have been recently reviewing all of Dashdev’s projects from last year. As an outsourcing company, we in just one month worked on 30 different projects. To add to the fact, every project had integrated at least three external services.
Deciding to open your API
At some point in time, a company will arrive at the decision of whether to share the access to API to the rest of the world or not. There can be different reasons for doing it:
- Existing requests - other companies want to integrate with your API.
- A strategic business decision – you know how to promote your services to become commercially successful.
- Regulatory requirements – some UK financial institutions must have an open API according to the PSD2 regulation. This initiative is called Open banking.
- The competitors did it – sometimes it is simply necessary to follow suit. This is often the reason why companies spend tons of money on the development of an API.
All of the reasons are valid at some point. An open API can increase a company’s valuation. The number of real users of your service will multiply. However, at the same time, having a public API can bring you more problems than you expect: Productivity, time for development and maintenance, and the costs of promotion can quickly drain your money and working capacity.
However, these issues don’t necessarily stop companies from taking this step. The goal of this article is to help you open your API with fewer issues.
At first glance, the task of creating a public API is purely technical. Why does the product owner talk about it? It is because an open API is an impersonation of your product that has been modified to the target audience. Basically, the product will communicate with other products/companies/services. It must be aligned with the brand voice. From this perspective, open API becomes the product owner’s responsibility too.
If you’ve read any of my articles before, you already know that you’ll find a lot of questions in them that are relevant to you. I believe that this is the best way to learn and to teach somebody. You need to understand the reason for the action before you do it. A simple checklist is a bad solution. This article is not an exception. I’m going to lead you through my way of thinking when I released an open API feature for one of my products.
Structuring your thoughts
Thinking about the process of opening an API can make you, as the product owner, panic a little bit. That’s why our first step will be to create a structure or framework for future product extension. Let’s divide the process into 6 blocks:
- Which business needs can be meet with an open API?
- What API are you going to share?
- How are you going to share the API?
- How to manage access to the API?
- How are you going to support the API?
- How do you analyze the results?
Which business needs can be meet with an open API?
I put this question first because it is necessary to understand the reason for sharing a part of your product. Another related question that can help you is: How will you know that the product is successful? What are the applied metrics that help you achieve success? Ask your business owner about it. The answers may help you manage expectations and correlate your marketing strategy. The result of this item will be the set of strategic goals and the list of performance tracking metrics that will help you accomplish those goals.
What API are you going to share?
First of all, you need to select the functionalities you are going to share. Imagine a few companies that will use your API. Think about the problems they going to solve with it. Think of how you can make this process smooth and profitable. Depending on the product, you may need to open the entire API or just a part of it. After you create the use cases, you need to compare them with your business needs. Will this list help you achieve the goals that your business has? The results of this item will be the list of APIs with supporting use cases.
How are you going to share the API?
In general, there can be 2 basic approaches to creating an open API - access to the existing API or develop a dedicated API. If you imagine your product as a house, your current internal API is a door to the Database, services, and processes. Using an existing API is like giving your neighbor a key to this door. A dedicated API is like creating another door that has access only to one cramped room. This entrance has a new approach to its access - new locks and keys. Both of the options are acceptable and are being used.
Using the existing API:
- This approach is easier to achieve because you already have everything developed, you just need to describe everything.
- It is easier to manage API updates. You can deliver one change for your internal and external users, which means less time spent on testing.
- It is more convenient to control all the users of the services.
Creating a dedicated API:
- It is a more secure approach. You may develop an addition authorization flow.
- The connection is more manageable. First of all, you can define which partner overloads your system. You even can set up tiers on the number of connections.
- Analytics is applicable. Remember, we discussed the metrics a little bit earlier. Using a dedicated API helps you divide the server’s load into internal and external.
- Additional development is needed.
This decision must be made based on security and technical restrictions with consideration of the business needs.
How to manage access to the API?
Broadly speaking, the developers need to be given access to your API. It can be done in three ways:
- totally free access - no registration from our side;
- partially free access but accessible only after the registration on the developers portal; and
- paid access – a one-time payment, monthly fee, or limitations for the number of requests.
Let’s start the discussion here from the decision of whether it is necessary to validate the users of your API. If your service is just sending Push-messages, you don’t need to control the users of your API so precisely. If you are a card processor, you need to check that the company has permissions for the trading activity or licenses.
So, do you need to validate the partners? If you do, then you need to describe what information you need to know about them. This information will be the core of the partner’s registration. One partner may have a few applications. Therefore, you need to think about how to identify this application in your system. The approaches that you can apply are either token or applicationID. The identifier is added to each request to your system. The result is in two sets of user-stories: one is for the registration of the partner, and the other for the registration of the application itself.
How are you going to support the API?
Every open API must have a place where partners can find answers to the questions, claims for help, or where to report an issue. That’s why FAQ and API description pages are required.
Sometimes your partners have some issues or questions they want to ask a technical person. If your product is a hi-tech solution with a significant number of dependencies, you may consider hiring a technical support team.
Commonly used approaches for support communication:
- Email is certainly the simplest, but the most hated by developers. You never know the destiny of the email you wrote. It can get to the spam folder, or simply be overlooked and be left unopened.
- You can choose to integrate a tool for tickets/chat. Great examples are Zendesk or Intercom. The user may write to a chat-tool or create tickets.
- You can create complaint forms on your site and integrate it to your Jira via the open API.
- Forums are also a common approach. The exciting solution is to provide a place for developers to share their experiences and help each other. The downside, however, is that the moderation of communication is time-consuming.
A substantial improvement that can help you, your partners and your support team is a monitoring system. You can create a status page with the list of APIs. This will be the place where your users can find the actual status of the system without contacting your customer support team.
From the other side, this page will help your team proactively fix all the production issues.
The result of this step is the list of user stories to maintain the support process. Additionally, I would suggest creating requirements for your monitoring system.
How to analyze the results?
I started to write this article with a question about metrics, and how they are used in the creation of a successful product. Now is the high time to speak about it again. I want to discuss how exactly you should plan to analyze it. I suggest that you develop a special dashboard with the key events that you are tracking. If you save all the historical data, you’ll be able to analyze and make some predictions of the load for the future. The only notice here is that you need to track not only successful requests but failed cases as well.
As the result of this step, you have a list of user stories for your analytics and dashboard.
If you think that the most exciting part is over, you are wrong. These are only the basic functional requirements that can help you define the amount of work that needs to be done.
The next steps will be related to the design, non-functional requirements and architecture design.
After you open your API, the life of your business will change.
Just keep in mind that:
- during all future feature planning, you’ll need to check if these updates do not influence the open API negatively;
- the time for testing before the release will be increased because you need to check that the open API works correctly;
- you will need to plan developers’ time to support/fix some issues;
- the users of your open API are your users too. You need to check if they like using your product. Consider their opinion for future development; and
- communication services like email campaigns, marketing messages, and promotion plans must be aligned and executed too.
Working with digital products is really exciting. Every day you can change your business significantly with just one idea. Love your product and think about how you can make it better.