1. Scaling API DesignJason Harmon, Head of API DesignOctober 2014 2014 PayPal Inc. All rights reserved.

2. About meScaling API DesignJason 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@jharmnJasonh-n-austin 2014 PayPal Inc. All rights reserved. 2 3. Lets think bigWhat if your startup takes off? 2014 PayPal Inc. All rights reserved. 3 4. Breaking down the monolithDistributed architectureDefine uniform interfacesAllow for scaling per capabilityIncrease team autonomyDiscoverability is hard in big systems 2014 PayPal Inc. All rights reserved. 4 5. PortfolioThink about the big picture 2014 PayPal Inc. All rights reserved. 5 6. Organizing your APIsPortfolioRespect customer languageInverse Conways ManeuverOrganizations which design systems areconstrained to produce designs which arecopies of the communication structures ofthese organizations. Dont design your APIs to reflectyour systems or organizations Make your software look like yourcustomers see youhttp://www.thoughtworks.com/radar/techniques 2014 PayPal Inc. All rights reserved. 6 7. Business decides, developers implementPortfolioBusinessIdentify capabilitiesSometimes a capability is a resource collection (not always)Level 1 Categories + Package/Spec/Level 2DevelopersUse namespaces to designate functional areas: /v1/factory/widgets Not always the same as capabilities/packagesURIs relay data relationships 2014 PayPal Inc. All rights reserved. 7 8. Organizing your APIsPortfolioGroup operations by goals/usageAPI Product Managers can be helpfulStart with capabilities, not resourcesDiscoverability via dev portals Internal External PartnerUse caution with product names for capabilities 2014 PayPal Inc. All rights reserved. 8 9. Design firstRight after portfolio 2014 PayPal Inc. All rights reserved. 9 10. Building backend is expensiveDesign firstBreak changes early, before you build itSpecification formats Swagger, RAML, Blueprint: whatever suits you Portal/Docs/Reference Codegen server/client/SDK Mocking Consistency ValidationGet 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. FundamentalsCore elements of API design 2014 PayPal Inc. All rights reserved. 12 13. Be the client advocateObjectivityThe best API designs come from outside the delivery teamMake the servers job hard, so all the clients are easierDesign without implementation constraints as a first concernDont take a tour in the hot dog factory 2014 PayPal Inc. All rights reserved. 13 14. Long live v1!SustainabilityRapid iteration/fundamental changes are off-limitsRule #1 of API versioning: try not toThere are no extensible API designsCan we grow this design without starting over?Hide implementation details Todays backend is tomorrows scrap heapWatch out for implementation details in errorsAdd URIs, deprecate URIs Design iterations are usually new resourcesAPIUX: http://apiux.com/2014/09/05/api-design-sustainability 2014 PayPal Inc. All rights reserved. 14 15. Nouns matterUsabilityhttp://softexpert.files.wordpress.com/2007/10/526604Resource orientedAvoid RPC unless you can rationalizeoptimized DXUnderstandable terminology Use industry-standard terminology wherepossible Avoid vague terms: Metadata Context86_6ca085f7a8.jpg?w=780 2014 PayPal Inc. All rights reserved. 15 16. One API call is not enoughUsabilityGet your flow onCapture current and future use casesIdentify goals Analyze chain of calls and identifiersrequired to reach goalREST != CRUD Think beyond data structures, thinkresources Resources should quickly reach clientgoals without excessive complexity 2014 PayPal Inc. All rights reserved. 16 17. Design scale, not system scaleor bothScalabilityThe Goldilocks principleBe smart about just right sized resourcesBig 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 socketshttps://img1.etsystatic.com/000/0/5414982/il_fullxfull.191894533.jpg 2014 PayPal Inc. All rights reserved. 17 18. Stick to the planConsistencyStandards, patterns, guidanceNaming conventions Field, parameter, URIDefine HTTP interactionsIdentify common components Addresses, user info etcHeaders are platform plumbingConsistent identity mechanismshttp://minorcreations.files.wordpress.com/2012/07/one.png 2014 PayPal Inc. All rights reserved. 18 19. DecentralizeEducate and cooperate 2014 PayPal Inc. All rights reserved. 19 20. Be a good listenerDecentralizeRaise awarenessListen to feedback on gaps in understandingConduct regular feedback sessions Frontend and Backend devsHackathons inside & outDocument anything you have to answer twiceStandards are requisite, but guidance is betterHighlight outstanding examples of design andcollaboration https://graysdeafblog.files.wordpress.com/2010/08/ear-horn.jpg 2014 PayPal Inc. All rights reserved. 20 21. Educate and cooperateDecentralizeInternal evangelismEducate developers Program/process Standards & principlesIdentify thought leaders API design mentorship Ongoing communication 2014 PayPal Inc. All rights reserved. 21 22. Scaling API DesignTack!Jason HarmonHead of API DesignPaypal@jharmnJasonh-n-austin 2014 PayPal Inc. All rights reserved. 22