We’re an API-first company that solves the complex problem of identity fraud for a large, global customer base. We’ll share stories of how we’ve adopted and adapted our API growth and governance strategy, product development process, and approach to developer experience as we’ve scaled.

1. David Vilf and Phoebe Baxter
Scaling your API product strategy

2. Onfido - Confidential &
Proprietary
The Onfido API sits at the core of
our product offering
Onfido’s vision is to
“create an open
world where identity
is the key to access”

3. David Vilf
Product Manager - Client Experience
Onfido
Phoebe Baxter
Technical Writer - Client Experience
Onfido

4. Team mission
ATTRACT ACTIVATE INTEGRATE
🎯 Build a fast, robust and frictionless product experience that caters towards all core
customer integration needs and converts and retains customers at scale. From trials, to
integration all the way to long-term engagement.
💰 👩💻 😍
ENGAGE

5. Discussion topics
1 Concealed challenges when scaling your API product
2 Creativity, focus and communication as success ingredients
3 Insights into Onfido’s API governance strategy

6. Concealed challenges when
scaling your API product
“Every rose has its thorn”

7. The API is the product

8. API products come with clear advantages...
Scalability Flexibility Openness

9. …but rapid API product scaling also brings challenges!
How do you…?
Keep a rapid
cadence of shipping
software, without
breaking customer
integrations?
Evolve API design
while guaranteeing
API contract
reliability?
Avoid internal
bottlenecks and
maintain a high
standard of the
software you ship?

10. API v2
POST /v2/applicants/{applicant_id}/checks/
{
"type": "express",
"reports": [
{
"name": "document"
},
{
"name": "facial_similarity",
"variant": "standard"
}
]
}
OLD API v3
POST /v3/checks/
{
"applicant_id": "<APPLICANT_ID>",
"report_names": ["document","facial_similarity_photo"]
}
NEW

11. …but rapid API product scaling also brings challenges!
How do you…?
Keep a rapid
cadence of shipping
software, without
breaking customer
integrations?
Evolve API design
while guaranteeing
API contract
reliability?
Avoid internal
bottlenecks and
maintain a high
standard of the
software you ship?

12. …but rapid API product scaling also brings challenges!
How do you…?
Keep a rapid
cadence of shipping
software, without
breaking customer
integrations?
Evolve API design
while guaranteeing
API contract
reliability?
Avoid internal
bottlenecks and
maintain a high
standard of the
software you ship?

13. Embracing tradeoffs between reliability & speed
API
USERS
ONFIDO
TEAMS
API
VERSIONING
POLICY
● “Every changed / deleted / added
field should be versioned”
● Need for predictability & reliability
“I need to ship new features
that clients can start using
tomorrow!”
?
🏎
⚙️

14. Creativity, focus and
communication as success
ingredients
“Pushing the boundaries, find a better way”

15. “Commitment to no API schema changes of existing public API versions.”
Creative tailoring to customers’ release expectations
Backwards incompatible
changes
● Removing a feature of the API
● Renaming a resources, field,
method or enum value
● Changing the type of a field
Major (v4, v5..)
Backwards compatible
changes
● Adding new properties to the
responses from existing API
endpoints
● Adding new values to existing
properties in responses from
existing API endpoints
Minor (v4.1, v5.3..)
Independent features which
do not alter pre-existing logic
● New optional request
parameter
● New API endpoints
● New report
Current version (v3.1, v3.2)

16. Create focus by decoupling dependencies

17. Over-communicate, educate and install processes
🚂 Establish transparent release trains
🎨 Internal knowledge of API strategy and design
♻️ Internal ways of working (get “buy-in”)
📚 “If it’s not documented, it’s not done”

18. Scaling rapidly for 1,000s of customers and
millions of end-users
Insights into Onfido’s API
governance strategy

19. Transparent Communication
Public API versioning policy

20. Team
dependencies
Ways of working
wiki
Transparent Communication
Internal documentation
Team
responsibilities
API governance for
product teams
Infrastructure
changes
Technical
considerations
Versioning
infrastructure
Design
principles
API design best
practices

21. Content Management
API version specific documentation
Federated search
Version switcher

22. Driving Adoption
Release notes
Migration guides

23. Developer Tools
Onfido API version specific Postman Collections

24. Schemas > reports > report.yaml
type: object
required:
- name
properties:
id:
type: string
readOnly: true
description: The unique identifier for
the report. Read-only.
created_at:
type: string
readOnly: true
format: date-time
description: The date and time at which
the report was first initiated. Read-only.
....
Developer Tools OpenAPI specification
Schemas > reports > report.yaml
allOf:
- type: object
readOnly: true
properties:
id:
type: string
readOnly: true
description: The unique identifier for the
report. Read-only.
....
- anyOf:
- properties:
name:
enum: ['document',
'document_with_address_information',
'document_with_driving_licence_information']
breakdown:
$ref: document_breakdown.yaml
properties:
$ref: document_properties.yaml
....

25. Key takeaways

26. Key takeaways
Never underestimate transparency, communication & processes
⚖️ Acknowledge tradeoffs between internal and external stakeholders
Good execution of API governance is a product differentiator

27. Thank you
For any further questions, contact us under:
David Vilf - david.vilf@onfido.com
Phoebe Baxter - phoebe.baxter@onfido.com