Phoebe Baxter & David Vilf - Scaling your API-first product strategy

”Our mission as a team is to ensure our customers can integrate and consume the Onfido product experience in the most optimal way. Important for us is to build a fast, robust and frictionless product experience.”

1. Concealed challenges in rapid scaling
2. Essential for success: creativity, focus and communication
3. Onfido's API governance

Advantages of an API first business model:

• Scalability: API as a distribution mechanism allows rapid scaling, especially the ones that specialize into one specific domain and one specific use case and are then connecting to a number of other APIs. Flexibility for the integrator:
  • Full control over the end user experience: ability to choose how to consume and present information and the way they want the design and the look and feel to be for their end users.
  • Modularity: users can see what is available within an API and effectively build an application or their product on top of that API, choosing the preferred parameters and logic.
• Openness: APIs allow for transparency, clarity on the methods and the data that can be obtained.

Challenges with rapid scaling:

1. How do you evolve API design while guaranteeing API contract reliability? Product strategy and customer needs will change and technology companies have to evolve as well. While the API evolves in its design and schema, one has to still respect the contract that has been made with the customers.
2. How do you keep a rapid cadence of shipping software without breaking customer integrations? Understand early on in the design process of an API's new feature or improvement how your integrators can relate, balance speed with stability, to avoid later delays.
3. How do you avoid internal bottlenecks and maintain a high standard of the software you ship? Growing number of product teams, changing specialization: you are not only scaling what is on the devportal or on the technical reference. Internally the teams change, evolve and adapt, and that is a massive consideration to factor in.

”There is really a trade-off between API users (our customers) where there is a need for predictability and reliability, and our Onfido product teams who are in this race of fighting and preventing identity fraud. We want to ship software as fast as we possibly can, but of course there is this tension.”

Executing on the API versioning strategy:

• Current version for independent features: don’t alter pre-existing logic.
• Minor versions: getting released for backwards compatible changes.
• Major versions: being released for backwards incompatible changes.

”It is the commitment we give to our customers that every public API version will not have any schema changes, unless it meets these criteria.”

Create focus by decoupling dependencies

”Are there specific efforts that can be decoupled? How can we better arrange our teams so that we avoid dependencies and we can ship as fast as we possibly can, while of course maintaining high standards?”

Over-communication, education and install processes

”Communication is a key success ingredient for implementing an API governance strategy. This is why we have adopted an open and transparent approach to our public documentation at Onfido.”

• External documentation as the source of truth, both internally and externally.
• Focusing on internal knowledge of API strategy and design.
• Establishing transparent release trains to manage expectations.

API governance strategy insights

The success of an API governance strategy partly depends on the ability to get customers to upgrade to new versions. It is important to acknowledge the balance between the upgrade effort on a customer’s part and the benefits they receive as a result.

Driving adoption

Onfido’s API versioning guide outlines how and why they version, how to upgrade support timelines and virtual information for their client libraries and webhook events.

• Publishing release notes in a way that encourages less technical stakeholders to understand and embrace the benefits of upgrading.
• Providing comprehensive migration guides between versions, highlighting key differences and schema changes between versions.

Users can anticipate version cadence, understand the impact on their integration and the differences between minor and major releases. This meets user needs for predictability and reliability with API changes.

Clear internal documentation, open lines of internal communication:

• Ways of working wiki: outlines team processes and responsibilities to optimize productivity and product delivery
• API governance documentation: detailing team responsibilities for contributing teams as well as the release team
• Infrastructure changes: technical considerations and versioning as a result of API development
• API design best practices

Key features in technical reference

• Version specific API reference pages, including code examples, links to relevant integrated tools and new features.
• Custom built version switcher.
• Integrated federated search, showing potential matches from across all of our available content.

As a result, Onfido’s internal documentation suits the needs of internal stakeholders, accommodates the product teams to ship features and gives clarity over the decoupling efforts.

Strategic use of developer tools

Postman collections:

• Internal: validates functionality and generates example requests and responses
• External: helps customers test and understand the new features available in new version

OpenAPI specification: describes and defines APIs in both a human and machine-readable ways allowing customers to understand and integrate with the service faster.

Key takeaways

• Never underestimate the power of transparency, communication and a robust process.
• Acknowledge tradeoffs between the sometimes competing needs of internal and external stakeholders.
• Good execution of API governance and the prioritization of this domain is vital and a product differentiator.