PayPal's APIs had become complex over time, making integration difficult for developers. To address this, PayPal redesigned their APIs based on basic principles focused on end users and developers. This included establishing clear API standards, following a design process involving use cases and resource modeling, and improving the developer experience with documentation, tools, and support. The goal was to simplify their APIs and platform to increase business agility while extending their reach through developers.

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

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

3. 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)

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

5. PAYPAL APIS HAD BECOME …

6. PAYPAL APIS ARE GETTING HERE …

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

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 calls
based 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) Don’t repeat yourself in your
implementation, but don’t 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
analysis
Feedback
API
Specification
Capability
Mapping
Resource
Modeling
REMARKABLE 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 STRATEGY
•
Backward 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 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

23. THANK YOU!
@ppalavilli @deepak_nadig