Ovidiu Silaghi

Your API Is a Product Too

The Context

I have heard and experienced the following story multiple times (or variations of it): you have to build a product that has a backend and frontend. Your product might need to interact with other products where those products consume some of your data. You might even have a mobile app that is consuming your data or part of it. The common solution in these situations is to build an Application Programming Interface (API) which will be consumed afterwards by your frontend, the mobile app, and other products. Up until now, no surprise.

The Challenge

Now comes the interesting part. Most probably you will have a deadline for releasing everything into production and you will want Frontend and Backend to progress in parallel. You will probably also want that by the time you release your API, the frontend, mobile app, and other products to be able to consume your API. You hope they will not request you to make big changes on the API after you release it. It is probable that the mobile app and other products are developed by other teams or even other companies. 
What would be your approach? How would you synchronize people working on API with the ones working on the frontend? How would you synchronize people working on the mobile app or other products with people working on API? How would you make sure that the consumers of your API will not be surprised by what you deliver? How would you make sure to take into account some of their requirements so that you do not have to make many changes after releasing? 
Most of the time, what I’ve seen happening is a version of the following: people working on the API, in the best case, will meet with the ones working on frontend and have a few discussions on how the API will look. If you are lucky, maybe somebody will reach out to the mobile app team and other consumers of API teams and tell them that you are working on an API and ask them what they need.
After all these discussions they will start working on the API. A few months later the API is ready to be consumed. Maybe there were even some demos in between or who knows maybe some of the consumers asked for access to your staging in order to start consuming the API.
You probably applied recommended practices in developing the API and you are proud of the quality of it. 

What Could Go Wrong?

Your API might be ready and you are proud of what you’ve obtained, but most probably frontend people, mobile app team and other consumers of the API are not that happy. They are not happy because the API is hard to consume or even worse, they cannot implement their functionality because they need other data from you or they need other types of requests.
They might not be happy because when consuming your API, they realize that there are performance and scalability issues they weren’t aware of and which were hard to predict. At that point, you will probably start discussions about changing your API or developing adaptor APIs for your consumers. 
What if you are working in a domain that requires meeting compliance requirements or heavy security? Imagine you bring that API to those teams who are doing the security or compliance and they ask you to do multiple changes because you do not meet their requirements. 
So after all those months of hard work you have a beautiful API with great quality code which cannot be used properly and doesn’t meet the needs of the consumers. I hope at that point you realize that you have failed! 
You failed because you didn’t realize that your API is in fact also a product. 

Treating API as a Product

Another approach, when faced with these kinds of situations and which could save us from failure, would be to treat the API as a product from the beginning. 
Let me explain what I mean: 
  • API - Application Programming Interface: as the name says it, API has an interface. So, why not treat that interface like a User Interface for a product. We could do mock API and test those in “user interviews” with the consumers. There are many options today to create a mock API (do a google search for mock API, mock API server)
  • If API has an interface, we should build one which is user-friendly because that will impact adoption. Even if the interface is consumed by developers, we should treat them as real users and we should care about developer experience with the API. 
  • Apply Product Mindset principles to the API. Minimize time to value by building small, and fast and delivering it to the customers so that we can learn quickly. 
  • Apply an API-First approach in building the API. See more details on swagger documentation
  • Ask consumers to use the API from the beginning by giving them access to a mock API. 
  • Ask compliance and security to do their assessments on the mock API so that we can incorporate their recommendations sooner. 
  • Develop endpoints in priority order driven by value-added to consumers and risk mitigations. Don’t let that main endpoint which is the most used to be developed last. Or that API which is complex and requires integration with a 3rd party to wait until the last sprints. 
  • Replace mock API’s endpoints with real endpoints as we develop them and notify the consumers. 
  • Do a kind of TDD for the API by writing tests against the mock API. Ask consumers to write tests on how they will consume the API. When we will have an endpoint ready we will also have tests validating that endpoint.
  • Put trackers in place for the endpoints so that we can learn and adapt as we release endpoints to consumers. 
  • Invite consumers to sprint reviews and send them updates as we make releases.  
I have seen and been part of teams building beautiful APIs and which have great quality code behind, but they haven’t built a successful product that generates revenue, is chosen by the users, and brings value. One of the reasons why we weren’t able to do this was our failure to treat the API as a product. Don’t let this happen to you!

Tags

More by Ovidiu Silaghi

Topics of interest