Consumers today are increasingly using a variety of applications across web, mobile, cars and devices to find information and/or to perform their tasks. In addition, Consumers are also using multiple modes of interactions - including touch and voice - with these applications. To deliver these variety of applications and natural interaction paradigms, companies need to develop API and service platforms that can be used by their internal developers as well as external developers and partners. In order to survive and be competitive, companies need to move quickly to deliver such platforms and features. It's Not the Big that Eat the Small... It's the FAST that Eat the Slow! Successful platforms, from companies such as eBay, PayPal, Amazon and Intuit, embody attributes such as delightful integration experience, flexibility and extensibility along with implicit developer expectations - security, quality, response time and availability. This talk will share a recipe for building and delivering platforms that developers love - principles, best practices and approaches - across architecture, organizational and cultural - used in companies such as eBay, PayPal and Intuit.

1. Deepak Nadig
Distinguished Architect, Intuit
New York Life Build Blue
May 19, 2017
Designing
API Platforms that Developers Love

2. 2

3. 3
Consumers Small Businesses Accounting Professionals
Who we serve:

4. 4
Era of the CloudEra of Windows Era of WebEra of DOS
2010+1980s 1990s 2000s
Proven track record: capitalizing on change
Intuit Founded
Quicken
DOS
IPO
Quicken
Window
s
QuickBooks
DOS
TurboTax Online
QuickBooks
Windows
TurboTax Windows
QuickBooks
MobileQuickBooks Online
QuickBooks
Online Global
• Employees: 150
• Customers: 1.3M
• Revenue: $33M
• INTU + 1,400%, NASDAQ + ~500%
• Employees: 4,500
• Customers: 5.6M
• Revenue: $1.04B
• INTU - 20%, NASDAQ - 40%
• Employees: 7,700
• Customers: 50M
• Revenue: $3.1B
• INTU +160%, NASDAQ 90%
INTUshareprice
SnapTax
Competitor
A
Competitor A Competitor C
Competitor A
Competitor A
Competitor B
Competitor
D
Competitor E

5. 5
# 1 Small Business Management. 7700
employees. $4.7 Billion in revenue.
QuickBooks has more than 5 million customers.
Online is 1.5 million (41% growth YoY).
26K developers. 2500 third-party apps. 15% of
customers use at least one third-party app.
Yearly, 100 million invoices; $1.5 trillion in
commerce; payroll for more than 1 million
employees (1/12 in US).
Small Business Owners spend 4 hours online
every day.
QuickBooks is in 112 countries.
Intuit and QuickBooks by the numbers

6. 6
The capability of rapidly and cost efficiently adapting to changes
- Wikipedia
The ability of an organization to sense environment change and
to respond efficiently and effectively to it
- Gartner
Challenge for businesses today = Agility

7. 7
Architecture Business Cycle
organization (who, together, fashioned the quality-attribute requirements), the technical
environment, and the architect’s experience.
In our adaptation of the ABC, the “influences” have been replaced by a set of forces that
collectively shape the requirements and, over time, the architect’s experience. The
extended ABC is depicted in Figure 1.
Figure 1: Extending the Architecture Business Cycle to Include All Design Forces
Notice that this extended ABC shows the requirements as being categorized into three
overlapping sets: quality-attribute requirements (e.g., the system should initialize itself
in 60 seconds), business requirements (e.g., version 1.0 must be available to our
resellers by August 1), and functional requirements (e.g., the system must provide
monthly sales summaries, broken down by region). These requirements, along with the
Software Engineering Institute http://sei.cmu.edu/
Architecture Business Cycle has impact on Architecture, Business and Culture

8. 8
• Architecture journey
• Business journey
• Culture journey
• Current à Target ABC
S-Curve
Business
Performance
Time
Kickoff
High
Growth
Limits
Reached
ABC
ABC
ABC
(*) ABC = Architecture Business Cycle

9. 9
Flexibility and Extensibility
Flexibility
Ease with which a system or component can be
modified for use in applications or environments other
than those for which it was specifically designed
Extensibility
Ease with which a system or component can be
modified to increase its functional capacity
IEEE Standard Glossary of Software Engineering Technology

10. 10
Agility is enabled by Flexibility and Extensibility
APIs enable flexibility
Microservices enable extensibility
Why APIs and Microservices?

11. 11
Journey begins as one of the following …
UI and
Business Logic
Web Browser
Web UI
Web Browser
Business Logic
Web UI
Web
Browser
Business Logic
Mobile UI
Mobile
Web UI
Web
Browser
Business
Logic
Mobile UI
Mobile
We need microservices!
Why are we still slow?
We need mobile!
No time to refactor
Develop feature N times
Just wantto tweak UI!
How do we organize?
Yay! Growingfast
One language
Slowing releases

12. 12
Target State
API Definition Internal or External Universal
API Discovery Painful Developer Portal
API Design Project specific API as a Product
Architecture Tightly coupled SOA Loosely coupled SOA
Technology Proprietary Standards based
Integration Expensive TTFHW* < 5 min
(*) TTFHW = Time To First Hello World

13. 13
Portfolio of APIs
aligned by business capabilities,
realized by isolated and encapsulated services,
that can be used by internal and external developers
to develop applications and integrations
quickly and cost effectively
API Platform

14. 14
API Platform Principles
API First
API Design
• Think API before experience
• API is a product
• Externalize-able
• Domain model & Integration scenarios
Developer Experience
• Easy to learn, integrate, diagnose
• Be the ‘developer’
API Quality Attributes
• Response-time
• Availability
Service Architecture
• Encapsulated, Isolated
• Craftsmanship

15. Best Practices
API as a product
API design
Experience vs Capability API
API specification
API documentation
Service granularity
Service development
API testing
API status & support
Developer Portal

16. 16
End users
Understand Segments
Their Experiences
And Expectations
Developers
Tools and processes
Their Integration needs
Be Transparent on usage
API as a Product

17. 17
API Portfolio
Define bounded contexts/capabilities
Organize cohesive concepts
Use orthogonality or distance to separate
API Design
Use problem space for domain model
Encompass all interactions – Events, Batch
Dog food API (and events)
Share design guidelines (apistylebook.com)
API Design
id
id
/invoicing /payments
/risk
DomainModel à API
• Entities, Attributes
• Verbs
• Relationships
• State machine

18. 18
Capability API
What API teams deliver
Optimizedfor API provider
REST, Batch, …
Experience API
Personalized for end user experience
Make it self-service for developer
Plan for multiple- GraphQL, Groovy
Experience vs Capability API
API Facade
Invoicing Payments Customer
Experience API
Capability API

19. 19
Many choices
OAS*, JSON Schema, RAML
1 domainmodel, N experience APIs
Generate Docs, SDK, Tests
Maintain specification as code
GitHub, GitFlow(agile versioning)
Fail builds – enforce validation
Pull Request - customer review
API Specification
(*) Open API Specification

20. 20
By developers for developers
Developers contribute documentation
Technical writers play editor role
Include in release process
Maintain documentation as code
GitHub, GitFlow(version w/specification)
Fail builds – automatedvalidation
Open it for community contributions
API Documentation

21. 21
Why you should care?
Extensibility
Granularity Principles
Team boundary
Security
Rate of change
Scalability
Cohesion
Service Granularity
Credit: Spotify Engineering Culture

22. 22
Getting to microservices
Code complexity vs. change
Pick the first, complete, repeat
Team autonomy, diagnosingissues
New microservice
Plan for multiple languages
Plan for CI
Team (4) > Team (2) (45% more time)*
Service Development
Complexity
Low
High
High
Low
Least priority
Low priority
Impacting cycle
time
Easier to
decompose
Start here
Impacting cycle
time most
Decompose,
then refactor
Change
(*) The team scaling fallacy: Underestimating the declining efficiency of larger teams

23. 23
API Testing
Test independently
Use API specificationfor automation
Complete scenarios (with Webhooks)
Sandbox
Sandbox = Production
For internal and external developers
Automatedtestingfor external developers
API Testing

24. 24
API Status
Developers need to know
Healthdashboard
Report status promptly on issues
Diagnosing issues
Treat developers alike
Provide API logs with messages
Be proactive using API analytics
API Status & Support

25. 25
Complete developer experience
For 1st and 3rd party developers
Time To First Hello World < 5 min
Developer Portal

26. Culture

27. 27
A way of thinking, behaving, or working
that exists in a place or organization
- Merriam-Webster
Behavior of humans within an organization and
the meaning that people attach to those behaviors.
- Wikipedia
What is culture?

28. 28
Application development
Web page design Process
Site design/Portfolio Management
Engineers work with page designs
API development
API DesignProcess
API Portfolio Management
Engineers work with API designs
API Engineering Processes
App. Product
Manager
UED*
Application
Engineering
API Product
Manager
API
Designer
Service
Engineering
(*) UED = User Experience Design

29. 29
Be aware of Conway’s law
Namespace != Organization
Reuse = Coupling
Agreements based on standards
Teams evolve at different rates
Use maturity model to measure
Organization Evolution
How do committees invent?

30. 30
Build something in 24 hours
Internal hackathons
Usability testing for APIs
Pride of ownership for API teams
Developer advocacy
Hackathons

31. 31
• Agility is a business imperative
• Agility comes from flexible and extensible
architectures
• APIs enable flexibility
• Microservices enable extensibility
• Architecture and culture need to evolve together
Summary

32. Thank You
@deepak_nadig