Video and slides synchronized, mp3 and slide download available at URL http://bit.ly/KqilTU. Deepak Nadig, Praveen Alavilli present how PayPal redesigned its APIs based on lessons learnt developing their services in over 14 years, and the principles, patterns and anti-patterns used in API design. Filmed at qconsf.com. Deepak Nadig heads Platform Engineering at PayPal. In this role, he leads the team responsible for delivering PayPal’s APIs and Developer Experience for external and internal developers. Praveen Alavilli is the architect for the Developer Products at PayPal helping in building the next generation APIs, tools and resources for external developers.

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

2. Watch the video with slide
synchronization on InfoQ.com!
http://www.infoq.com/presentations
/redesign-PayPal-APIs-scalesimplicity
InfoQ.com: News & Community Site
• 750,000 unique visitors/month
• Published in 4 languages (English, Chinese, Japanese and Brazilian
Portuguese)
• Post content from our QCon conferences
• News 15-20 / week
• Articles 3-4 / week
• Presentations (videos) 12-15 / week
• Interviews 2-3 / week
• Books 1 / month

3. Presented at QCon San Francisco
www.qconsf.com
Purpose of QCon
- to empower software development by facilitating the spread of
knowledge and innovation
Strategy
- practitioner-driven conference designed for YOU: influencers of
change and innovation in your teams
- speakers and topics driving the evolution and innovation
- connecting and catalyzing the influencers and innovators
Highlights
- attended by more than 12,000 delegates since 2007
- held in 9 cities worldwide

4. THE PAYPAL CONTEXT
PayPal …
– 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 day
In a dynamic environment
– 300+ features per quarter
– We roll 100,000+ lines of code every two weeks

5. PAYPAL PLATFORM EVOLVED
TO SUPPORT INTEGRATION NEEDS
2001 Instant Payment Notification
2004 Transaction, Mass Pay API
2005 Direct Payment API, Express Checkout
PayPal API
2007 Payment APIs (NVP)
2009 Adaptive APIs (SOAP/XML, NV, JSON)
PayPal Capabilities
2013 Payment APIs (REST)

6. REALITY WAS…
Async APIs
Client Apps
Client APIs
Mobile Apps
Backend
Web APIs
PayPal
Platform
Other
Platforms
SOAP
APIs
Web Apps
Batch
APIs
Shopping
Carts
Hosted
Solutions

7. PAYPAL APIS HAD BECOME …

8. PAYPAL APIS ARE GETTING HERE …

9. REDEFINED DEVELOPER PLATFORM
Reestablish credibility with the external developer community by building
simple & consistent APIs with easy discovery and integration
that extend our reach into the richer industry ecosystem
Multiple developer portals
https://developer.paypal.com
Overlapping, inconsistent APIs
Clear, consistent APIs
Learn from large documents
Learn from simple HTML, Tools
Complex sign-up
Simple as-needed sign-up
Incomplete, unreliable Sandbox
Complete, reliable Sandbox
7

10. 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, …

11. ELEMENTS OF SUCCESS
ü API Standards
ü API Design Process
ü Developer Experience

12. 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 calls
based on http://restcookbook.com/

13. 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) Don’t repeat yourself in your
implementation, but don’t worry
about repeating yourself in your API
design.

14. 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"
}
]
}
}

15. THE API DESIGN PROCESS
Use-case
analysis
Feedback
API
Specification
Capability
Mapping
Resource
Modeling
REMARKABLE SIMILARITIES WITH
USER EXPERIENCE DESIGN PROCESS

16. 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

17. 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}
…

18. VERSIONING STRATEGY
•
Backward compatibility is
critical
•
•
But, versioning supported
https://api.paypal.com/v1/…

19. 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!

20. 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

21. FEEDBACK
• Mechanisms
• Hackathons with internal and
external developers
• Developer council
• Measure
• TTFHW
• Integration effort
• Errors

22. DEVELOPER EXPERIENCE
• Documentation & Tools
• Sandbox
• Quick sign-up
• Integration monitoring and diagnostics
• Technical support

23. DEVELOPER EXPERIENCE

24. 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 PayPal’s 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

25. THANK YOU!
@ppalavilli @deepak_nadig

26. Watch the video with slide synchronization on
InfoQ.com!
http://www.infoq.com/presentations/redesignPayPal-APIs-scale-simplicity