1. REDESIGNING PAYPAL APIS FOR SCALE AND SIMPLICITY Praveen Alavilli, Deepak Nadig

2. THE PAYPAL CONTEXTPayPal 137 million active accounts 193 markets in 26 currencies 2012: Total Payment Volume was $145 billion Q3 2013 Total Payment Volume of $44 Billion At $5580 TPV / second Growing 25% YoY 729 million transactions 8 million payments every dayIn a dynamic environment 300+ features per quarter We roll 100,000+ lines of code every two weeks 3. PAYPAL PLATFORM EVOLVED TO SUPPORT INTEGRATION NEEDS 2001 Instant Payment Notification2004 Transaction, Mass Pay API2005 Direct Payment API, Express CheckoutPayPal API2007 Payment APIs (NVP)2009 Adaptive APIs (SOAP/XML, NV, JSON)PayPal Capabilities 2013 Payment APIs (REST) 4. REALITY WAS Async APIs Client Apps Client APIs Mobile Apps BackendWeb APIs PayPal PlatformOther PlatformsSOAP APIsWeb Apps Batch APIs Shopping CartsHosted Solutions 5. PAYPAL APIS HAD BECOME 6. PAYPAL APIS ARE GETTING HERE 7. REDEFINED DEVELOPER PLATFORMReestablish credibility with the external developer community by building simple & consistent APIs with easy discovery and integration that extend our reach into the richer industry ecosystemMultiple developer portalshttps://developer.paypal.comOverlapping, inconsistent APIsClear, consistent APIsLearn from large documentsLearn from simple HTML, ToolsComplex sign-upSimple as-needed sign-upIncomplete, unreliable SandboxComplete, reliable Sandbox7 8. STARTED FROM BASIC PRINCIPLES Who are the end users? customer segments, expectations Who are the developers ? developers, merchants, system integrators How should we design our API ? sync, async, batch, errors How should we ease learning ? docs, API explorers, HATEOAS console, How should we simplify integration ? familiar standards, SDKs, support, 9. ELEMENTS OF SUCCESS API Standards API Design Process Developer Experience 10. API STANDARDS API Standards External & Internal Resource model REST semantics URI format Environments Versioning Namespaces Extensibility Response codes Patterns Idempotency Web linking Filters Deletion of resources Pagination Message formats Data model Common data types Serialization Security Application identification Errors Error codes Identification of PayPal SDK's callsbased on http://restcookbook.com/ 11. REPRESENTATION & PATTERNS Using the JSON data model JSON serialization right now Specifying common, standard, I18Nready data types { "intent": sale", "payer":{ "payment_method":"urn:payment_method:credit_card", "first_name":"", "last_name":"", "funding_instrument":{ "credit_card":{ "number":1234123412341234, "type":"", "exp_month":12, "exp_year":2015, "cvv2":123 } } }, transactions":[ { "amount":{ "total":1.0, "currency":"USD" }, "payee":{ "id":"" } } ] } Relying on standard patterns as much as possible Specifying standard patterns to complement those: Transaction processing and avoiding duplication Selection of subset for item lists Error message format (DRY) Dont repeat yourself in your implementation, but dont worry about repeating yourself in your API design. 12. PATTERNS Controller Pattern https://api.paypal.com/v1/payments/payments/123/refund View/Filter Pattern https://api.paypal.com/v1/wallet/@me/funding-instruments/cards HATEOAS 201 Created HTTP/1.1 Content-Type: application/json { "id":1234134", "state":"approved", "transactions":{ "authorization":{ "id":908098", "state":"authorized", "amount":{ total":1.0 }, "links":[ { "rel":"self", "href":"https://api.paypal.com/v1/payments/authorization/908098" }, { "rel":"paypal:capture", "href":"https://api.paypal.com/v1/payments/authorization/908098/capture" } ] } } 13. THE API DESIGN PROCESS Use-case analysisFeedbackAPI SpecificationCapability MappingResource ModelingREMARKABLE SIMILARITIES WITH USER EXPERIENCE DESIGN PROCESS 14. USE CASE ANALYSIS Actors, roles, relationships, scenarios System boundaries Functional and non-functional requirements Error conditions and Contingencies Coarse grained or Fine grained Expected behaviors 15. RESOURCE MODELING Split business into functionality Modeling to identify: Entities Resource Actions on those: HTTP methods and controller resources Relationships and transitions Events (web hooks)Examples: https://api.paypal.com/v1/payments/payment/{id} https://api.paypal.com/v1/payments/authorization/{id} 16. VERSIONING STRATEGYBackward compatibility is critical But, versioning supported https://api.paypal.com/v1/ 17. AUTHENTICATION & AUTHORIZATION OAuth 2.0 User Approval/Consent Token Granting Public Clients Confidential Clients OAuth scopes to represent ability for an application to: Use certain functionality Access and operate on a resource E.g, capture funds authorized previously, read financial instrument from wallet, OAuth != Security Always use SSL Data at rest is always encrypted! 18. API SPECIFICATION Human & machine readable format Several options: Google Discovery Document Swagger IODocs WADL API Blueprint RAML JSON Schema GenIO: https://github.com/paypal/ genio 19. FEEDBACK Mechanisms Hackathons with internal and external developers Developer council Measure TTFHW Integration effort Errors 20. DEVELOPER EXPERIENCE Documentation & Tools Sandbox Quick sign-up Integration monitoring and diagnostics Technical support 21. DEVELOPER EXPERIENCE 22. SUMMARY APIs are an important way for a company, like PayPal, to extend reach Our APIs gathered entropy, which we addressed through good patterns Basic principles to deliver a great developer experience end users, developers, API design, learning, integration Successful APIs come from Familiar API standards Good API design process Simple and complete developer experience While transformation of PayPals external platform is underway The internal platform is going through a similar transformation Goal is about business agility Internal developer concerns are not that different 23. THANK YOU! @ppalavilli @deepak_nadig