Lesson Learned from Standardizing APIs In Hypergrowth Startup

Photo by Tingey Injury Law Firm on Unsplash

Background Story

I work in one of the fastest-growing startups in Indonesia at Xendit as API Product Manager. Xendit is one of the leading payment gateway in Indonesia and Philippines and we offer payment solutions for businesses to accept payments (Credit Cards, QR codes, eWallets, etc), disburse funds (Disbursements, Payout, etc), and other solutions suite mostly via API

During our early days, we experienced few API problems. To simplify the problems in few bullets:

Now, we are in a better position than we used to

The journey to get to this point is not easy and I want to take this opportunity to share the success/failure I experienced and few learnings of standardizing APIs from scratch if I have to do it all over again next time.

API Standardization Challenges

There are lots of challenges we faced to get to the state we’re currently at. I’ll group challenges into 3 main areas (sorted by highest complexity)

People

Process

Technology

Each area deserves its own page to explain further, but to keep it super simple here:

We’ll cover more in-depth for People and Technology in other posts if you’re interested to learn more!

In this post, I want to focus on setting up the Process as I think Process is often overlooked or not discussed as frequent as it should be by most people. We will cover the things I wish I knew earlier to set up a frictionless process to standardize APIs.

Setting Up API Standardization Process From 0 to 1

Setting up any processes from 0 to 1 is challenging and setting up one for API standardization has no exception

When we didn’t have API Standardization Process, the obvious next step was definitely to create API Design Guidelines so teams can refer to the standards to design APIs, but where do you/I start? What are the challenges that I find along the way and how do I overcome those?

The cheapest and quickest way is to start using global standards so let’s talk about it.

Use global standards. Don’t reinvent the wheel

Standards increase predictability and provide a great user experience. To quickly define API standards, we want to use existing global standards from ISO standards or RFCs available on the web to save time and research costs. Example of global standards are as follow:

You can also read API Guidelines from top API producers like Microsoft REST API Guidelines to get best practices inspirations.

By now, most of your problems should have been covered by global standards. Don’t unnecessarily reinvent the wheel. There are problems left remaining to be solved that are unique to your organization and it’s better to invest time and effort to design thinking and solve these problems.

Put together global standards that suit your company’s design language in Github Readme or Google Document for discoverability and you’ll get an MVP of API Design Guideline. I highly recommend you to get buy-in from key stakeholders by iterating with them frequently to enrich guideline knowledge.

Define organizational standards. Identify decision-makers

There were some areas left to be standardized and are unique per organization/company, for example, parameter naming, status naming, error messages, etc. There is no global standard for these areas. These standards are domain-specific per market, industry, product, user segment, or any other domain.

A quick example of the problem organizational standard is trying to solve:

Some users expressed confusion when they found different parameter naming in your API suite despite having the same concept/purpose and despite the fact that these APIs were produced by the same company.

For example, one API has amount parameter and another API hasnet_amount although they are intended to represent net amount or amount is a number but net_amount is a string for whatever ridiculous reasons.

Although documentation can help to solve the ambiguity, it’s always better to solve it from the root level by defining organizational standard to prevent future APIs to fall into the same misery/fate again.

Working to define organizational standards can be challenging and quickly turn into chaos if not done well. Jumping directly to gather stakeholders to discuss organizational standards rarely produce any decision because:

To be able to make organization standard decisions successfully, we’ll need to identify the decision-makers. This is the part I wish I knew earlier to run an efficient standardization process.

A simple framework I use to identify decision-makers is by grouping by the scope of domain area, starting from domain-specific areas that are unique per product until global domain:

Another framework I use to identify decision-makers is the RACI framework. RACI stands for Responsible, Accountable, Consulted, and Informed and provides clear discoverability of decision-makers to stakeholders.

By using either of these frameworks, when I need to standardize particular items, I’ll check who is the decision-maker, facilitate discussion among them, results in much faster decision making and better quality standards.

Snapshot of Standardization RACI framework

Timebox decision making and provide transparent timeline

Once I have identified decision-makers, I will work with decision-makers to make standardization decisions. Before I start working on a standardization item, I timebox standardization period usually at a maximum of 1 month. This means a decision must be made on the particular item in no more than 1 month.

In proposal item followed by estimated time to standardize it

This allows affected teams to plan to contribute and review proposed items and provides certainty to other stakeholders. The last thing I want to experience is to get yelled at by stakeholders of an uncertain timeline and these methods of timeboxing and timeline transparency are aimed to provide visibility of the standardization progress.

I set reminder to standardize items near the due date. If I need reviews from stakeholders, I set another reminder in Slack for stakeholders to review proposals.

Endorse start early behavior

Defining standards takes time to research and make decisions. Although timeboxing provides visibility to stakeholders, things move really fast in a startup company.

The problem emerged when standards are not ready to serve fast-pacing development and standardization process become the bottleneck. This bottleneck issue happened at Xendit especially during the early days of standardization process when our standards have not covered most surface areas.

To solve bottleneck problem, I encourage teams to start API design early, one-month early or three-months early, so we have time to uncover items that need to be standardized, work with decision-makers to research and standardize items.

Definitely, it will be naive to expect teams or projects to start early. Some projects are time-sensitive. Urgent impediments are the worst. When these projects came, we have limited or no time to conduct research and have to make standardization decisions in a short period of time that may impact the quality.

If you happen to be in this situation, I’d recommend assessing the return and risk of being politically correct (in terms of standards and API design) vs ship early and make trade-offs decisions accordingly. There is no right or wrong answer here, there is only how much risk we’re willing to take and how much return we’ll gain from the decision we made.

Conclusion

Setting up API standardization is important to provide predictable, consistent, and delightful experience to customers and allow teams to design and produce quality APIs. But there are variables we’ll need to consider that are “less fancy” and tend to be overlooked specifically in the process of setting up the standardization process.

We didn’t set up everything in a short amount of time. It took months and months to continue to improve the process and we’re happy to continue improving the process until years to come as we believe the value of providing best quality APIs to customers.

Here’s a quote that I really like and I value deeply

“If you think good design is expensive, you should look at the cost of bad design”

Here’s another quote that fuels my spirit to invest deeply in the standardization process

“Once your API has been officially released and integrated with your first stakeholder, your API design is forever.

You can add new endpoints and perhaps new fields to existing endpoint representations, but renaming or modifying existing endpoints will break existing API consumers, leading to upset customers and perhaps customer churn.

Getting it right the first time is important”Tyk.io

Let me know in the comment if you enjoy or find this story useful. I’m also curious to hear what API problems you’re facing so feel free to drop some comments so I can hear from you directly. Till the next post, stay safe friends!

Product Manager at Xendit. Alumni of ITB Informatics Engineering. Building payments infrastructure for SEA. Common sense, empathy, compassion, and mindfulness

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store