Scaling API Design

Scaling API Design
Jason Harmon, Head of API Design
September 2014
© 2014 PayPal Inc. All rights reserved. Confidential and proprietary.

About me
Scaling API Design
Jason Harmon
• Leads API design at Paypal
• Design phase of the “PPaaS” aka “Paypal as a Service" program
• Engineering-wide initiative
• Collaborate on designs for all internal/external/partner/whatever APIs
• Maintain style/standards
• Stakeholder for internal developer portal & tools teams
• Internal API design training/evangelism
@jharmn
Jasonh-n-austin
© 2014 PayPal Inc. All rights reserved. Confidential and proprietary. 2

Let’s think big
What if your startup takes off?

Distributed architecture
Breaking down the monolith
Everyone starts with a monolith
Defining uniform interfaces helps define bounded contexts
• Define interfaces, then perform surgery
Allows for scaling per capability
• When one component is overloaded, scale it!
• Harder to DDoS a distributed platform
Increases team autonomy
• Implementations can fit the need
• Languages & data don’t have to be all the same
Discoverability is a hard problem in big systems
• Reduce duplication of efforts
• Create visibility to weak spots in capabilities

Portfolio
Think about the big picture

Portfolio
Organizing your APIs
Group operations by goals/usage
API Product Managers are key, but they’re hard to find
Start with capabilities, not resources
• Identify capabilities by way of use cases
Provide internal/external/partner developer portals to provide visibility
Use caution with product names
Respect customer language
Inverse Conway’s Law
“Organizations which design systems are constrained to produce designs which are
copies of the communication structures of these organizations.”
• Don’t design your APIs to reflect your systems or organizations
• Make your software look like your customers see you

Portfolio
Business decides, developers implement
Business
• Identify capabilities
• How will business understand what your API can do?
• Sometimes a capability is a resource collection
• More often it’s a package of resources & operations
• Level 1 Categories + Package/Spec/Level 2
Developers
Use ‘namespaces’ to designate functional areas: /v1/factory/widgets
• Not always the same as capabilities/packages
URIs relay data relationships

Design first
Right after portfolio

Design first
Building backend is expensive
Break changes early, before you build it
Specification formats
• Swagger, RAML, Blueprint: whatever suits you
• Portal/Docs/Reference
• Codegen server/client/SDK
• Mocking
• Consistency Validation
Respect spec storage
• Separate from implementation, track minor versions on iterations
• All in one place – Platform skeleton
• Docs are specs too
Get API client feedback on mock APIs
• Real usability is only measurable with tactile feedback
• Weakness: multi-scenario and errors are hard to mock

Design first: Parallelize

Fundamentals
Core elements of API design

Sustainability
Long live v1!
• Rapid iteration/fundamental changes are off-limits once it’s released
• Extensible API designs aren’t really a thing
• Rule #1 of API versioniong: try not to
Can we grow this design without starting over?
Hide implementation details
• Today’s backend is tomorrow’s scrap heap
• Watch errors
Add URIs, deprecate URIs; new designs are usually new resources
• APIUX: http://apiux.com/2014/09/05/api-design-sustainability

Usability
Think about API clients’ perspective
Nouns matter
• Resource-orientation
http://softexpert.files.wordpress.com/2007/10/526604
• Avoid RPC unless you can rationalize optimized DX
• Understandable terminology
• Use industry-standard terminology where possible
• Avoid vague terms: metadata, context, etc
Get your flow on
• Capture current and future use cases
• Identify goals
• Analyze chain of calls required to get there
86_6ca085f7a8.jpg?w=780
• Pay attention to identifiers in each API to ensure they chain smoothly
REST != CRUD
• Think beyond data structures, think resources
• Resources should quickly reach client goals without excessive complexity

Scalability
We’re talking design scale, not system scale…or both
The Goldilocks principle
Be smart about “just right” sized resources
Big resources can be a problem
• System overload/performance issues
• Coupling concerns
• Long, unreliable HTTP connections
• Bandwidth overhead
• Complexity!
Tiny resources can be just as bad
• N+1 calls tend to proliferate
• Lots of TCP sockets https://img1.etsystatic.com/000/0/5414982/il_fullxfull.191
894533.jpg

Consistency
Stick to the plan
Standards, guidance, patterns
Naming conventions: Field, parameter, URI
Define HTTP interactions
• Common patterns
Identify common components
• Addresses, user info etc
Headers are platform plumbing
• Use them sparingly
Ensure consistent identity mechanisms
• Preserve external identity through
internal platform calls http://minorcreations.files.wordpress.com/2012/07/one.png

Decentralize
Educate and cooperate

Decentralize
Educate and cooperate
Internal evangelism
Educate developers on program/process, standard, and principles
Identify thought leaders and fast learners
• Develop API design mentorship
• Ongoing communication
Listen to feedback on gaps in understanding
• Conduct regular feedback sessions from frontend and backend devs
• Hackathons inside & out
• Dedicate to document anything you have to answer twice
• Standards are nice, but guidance is better
Highlight outstanding design and collaboration examples

Scaling API Design
Thanks!
Jason Harmon
Head of API Design
Paypal
@jharmn
Jasonh-n-austin

Scaling API Design

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Scaling API Design

Similar to Scaling API Design (20)

Recently uploaded

Recently uploaded (20)

Scaling API Design