Scaling API Design
•Download as PPTX, PDF•
4 likes•1,396 views
An overview of the Paypal PPaaS (Paypal as a Service) program. API portfolio management, goal-oriented design, design-first methodology, mocking. Decentralization of function through education and internal evangelism
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Similar to Scaling API Design
Similar to Scaling API Design (20)
Recently uploaded
Recently uploaded (20)
Scaling API Design
- 1. Scaling API Design Jason Harmon, Head of API Design November 2014 © 2014 PayPal Inc. All rights reserved.
- 2. 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. 2
- 3. Let’s think big What if your startup takes off? © 2014 PayPal Inc. All rights reserved. 3
- 4. Breaking down the monolith Distributed architecture Define uniform interfaces Allow for scaling per capability Increase team autonomy Discoverability is hard in big systems © 2014 PayPal Inc. All rights reserved. 4
- 5. Portfolio Think about the big picture © 2014 PayPal Inc. All rights reserved. 5
- 6. Organizing your APIs Portfolio Respect customer language Inverse Conway’s Maneuver “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 http://www.thoughtworks.com/radar/techniques © 2014 PayPal Inc. All rights reserved. 6
- 7. Business decides, developers implement Portfolio Business Identify capabilities Sometimes a capability is a resource collection (not always) 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 © 2014 PayPal Inc. All rights reserved. 7
- 8. Organizing your APIs Portfolio Group operations by goals/usage API Product Managers can be helpful Start with capabilities, not resources Discoverability via dev portals • Internal • External • Partner Use caution with product names for capabilities © 2014 PayPal Inc. All rights reserved. 8
- 9. Design first Right after portfolio © 2014 PayPal Inc. All rights reserved. 9
- 10. Building backend is expensive Design first 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 Get API client feedback on mock APIs • Real usability is only measurable with tactile feedback • Weakness: multi-scenario and errors are hard to mock © 2014 PayPal Inc. All rights reserved. 10
- 11. Design first: Parallelize © 2014 PayPal Inc. All rights reserved. 11
- 12. Fundamentals Core elements of API design © 2014 PayPal Inc. All rights reserved. 12
- 13. Be the client advocate Objectivity The best API designs come from outside the delivery team Make the server’s job hard, so all the client’s are easier Design without implementation constraints as a first concern Don’t take a tour in the hot dog factory © 2014 PayPal Inc. All rights reserved. 13
- 14. Long live v1! Sustainability Rapid iteration/fundamental changes are off-limits •Rule #1 of API versioning: try not to •There are no extensible API designs Can we grow this design without starting over? Hide implementation details • Today’s backend is tomorrow’s scrap heap •Watch out for implementation details in errors Add URIs, deprecate URIs • Design iterations are usually new resources APIUX: http://apiux.com/2014/09/05/api-design-sustainability © 2014 PayPal Inc. All rights reserved. 14
- 15. Nouns matter Usability http://softexpert.files.wordpress.com/2007/10/526604 Resource oriented Avoid RPC unless you can rationalize optimized DX Understandable terminology • Use industry-standard terminology where possible • Avoid vague terms: • Metadata • Context 86_6ca085f7a8.jpg?w=780 © 2014 PayPal Inc. All rights reserved. 15
- 16. One API call is not enough Usability Get your flow on Capture current and future use cases Identify goals • Analyze chain of calls and identifiers required to reach goal REST != CRUD • Think beyond data structures, think resources • Resources should quickly reach client goals without excessive complexity © 2014 PayPal Inc. All rights reserved. 16
- 17. Design scale, not system scale…or both Scalability 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 © 2014 PayPal Inc. All rights reserved. 17
- 18. Stick to the plan Consistency Standards, patterns, guidance Naming conventions • Field, parameter, URI Define HTTP interactions Identify common components • Addresses, user info etc Headers are platform plumbing Consistent identity mechanisms http://minorcreations.files.wordpress.com/2012/07/one.png © 2014 PayPal Inc. All rights reserved. 18
- 19. Decentralize Educate and cooperate © 2014 PayPal Inc. All rights reserved. 19
- 20. Be a good listener Decentralize Raise awareness Listen to feedback on gaps in understanding Conduct regular feedback sessions • Frontend and Backend devs Hackathons inside & out Document anything you have to answer twice Standards are requisite, but guidance is better Highlight outstanding examples of design and collaboration https://graysdeafblog.files.wordpress.com/20 10/08/ear-horn.jpg © 2014 PayPal Inc. All rights reserved. 20
- 21. Educate and cooperate Decentralize Internal evangelism Educate developers • Program/process • Standards & principles Identify thought leaders • API design mentorship • Ongoing communication © 2014 PayPal Inc. All rights reserved. 21
- 22. Scaling API Design Thanks! Jason Harmon Head of API Design Paypal @jharmn Jasonh-n-austin © 2014 PayPal Inc. All rights reserved. 22
Editor's Notes
- Define interfaces, then perform surgery When one component is overloaded, scale it! Harder to DDoS a distributed platform Implementations can fit the need Languages & data don’t have to be all the same Reduce duplication of efforts Create visibility to weak spots in capabilities
- Identify capabilities by way of use cases
- How will business understand what your API can do? More often it’s a package of resources & operations
- Identify capabilities by way of use cases
- Respect spec storage Separate from implementation, track minor versions on iterations All in one place – Platform skeleton Docs are specs too
- Use headers wisely Preserve external identity throughout internal platform calls