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:

• Few users expressed confusion on some of our APIs due to naming inconsistency
• Teams were using code-first approach instead of design-first approach
• We don’t have an internal API design guideline
• Teams cannot find any Xendit API standards

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

• We have a proper API design process to apply design-first approach
• We have established API design guidelines to record all Xendit API design styles and standards
• And most importantly, some of our APIs have been refreshed based on customers feedback to provide a simple, consistent, and delightful experience

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

• Not familiar with design-first mindset
• Didn’t possess the skills to design quality APIs

Process

• Didn’t know where to start to define standards
• Unclear ownership and decision making to define standards
• Unclear how long will it take to standardize items
• Unclear when standardization will take in-effect
• Unclear who will coordinate rolling forward standardization compliance for legacy APIs and when

Technology

• Didn’t know the tools to standardize APIs
• Didn’t know how to fit tools in the standardization process

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

• To solve for People: shift people’s mindset by influencing them directly or indirectly. Training is the most used method to influence people directly. Sharing articles or videos from top APIs producers are always a great way to influence people indirectly
• To solve for Technology: use openAPI, Swaggerhub, Stoplight, or Google Document

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:

• ISO 8601 for date and time format
• ISO 4217 for currency
• E.164 for phone number
• ISO 3166–2 Alpha 2 for country
• RFC 7807 for error structure
• RFC 7231 for HTTP 1.1 Semantics and Content
• RFC 2388 for file upload
• and many more you can find online

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:

• Some people are not knowledgeable or comfortable to make decisions
• No one wants to take the lead to be the tie-breaker to resolve different arguments/perspectives

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:

• Product Standard: Exclusive concept for a specific product. Example: Credit Card charges and refunds. Product Owner as decision-maker.
• Product Group Standard: Few or all product teams within the same group share the same concepts. Example: Money-in payment methods. Democratic vote across products within the group.
• Local Standard — Multiple Groups: Few or all product groups have the same concepts that need to be standardized. Example: Money-in and Money-out teams have amountconcept. Democratic vote across groups.
• Global Standards — API and market agnostic: Product, industry, and market agnostic standards. Example: Error Structure. API Team as decision-maker.

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.

• To get started quickly at a cheaper cost, use global standards to setup API standards
• Define organizational standards. Identify decision-makers early will help you to run decision-making meetings efficiently
• While working on making standardization decision, provide a transparent timeline so stakeholders are aware of the process and can plan accordingly
• Finally, in a hypergrowth startup where everything moves really fast, we’ll need to be flexible to make decisions in a short period of time. Endorsing starting early behavior to teams gives time to make quality standardization decisions

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!