PayPal operates in 200+ countries. The complexity of region specific requirements and a disjointed offering led to a situation where PayPal Checkout API product suite got polluted with many overlapping capabilities and an API documentation that was hard to comprehend, incomplete and inconsistent making the integration experience much harder than it needed to be. There was a strong desire to act upon the feedback that we have been hearing from our merchants and developer community to make a turn for the better. This talk aims to explore > When is the right time for organization to rethink their API and launch a new version. > Considerations that go into creating a new version of an API that is so central to the way thousands of developers and merchants integrate with PayPal. > Explore challenges in design, adoption, migration both internally and externally within the organization.

1. REBOOTING API’S AT SCALE
RAHUL DIGHE
CHECKOUT API PRODUCT @ PAYPAL
JAYADEBA JENA
HEAD OF API DESIGN @ PAYPAL
1
@rahuldighe

2. National Museum of the USAF
2
PAYPAL’S API JOURNEY
2004
2013
2018
PayPal launches one of the 1st NVP/
SOAP based APIs
PPaaS (PayPal-as-a-Service) setup with a
charter to provide governance and
accelerate migration to REST APIs. First
version (v1) launched.
Investment in v2 of our APIs begins.
First set of v2 APIs to launch soon.

3. YOU ARE NOT ALONE
SIGNS THAT YOUR API MIGHT NEED A REBOOT
▸ You have more features/capabilities but your
competitor steals the show because their API is easy to
understand and integrate with.
▸ API were built for a specific market/vertical use case
and now other partners are asking for it but it’s not
reusable.
▸ API’s have become bloated with fields/objects that
have organically grown and no one quite remembers
why you have it in the first place.
▸ API’s were designed for a country/locale in mind but
then the business grew internationally.
▸ API interface is not a business abstraction (instead
matches backend system implementation).
▸ API behavior is prone to idiosyncrasies of your
underlying system.
▸ Support engineers are critical to the success of your
integrations.
“IT’S TIME TO
THINK OF API’S
BEYOND JUST AN
INPUT /OUTPUT
MECHANISM TO
SOLVE AN
IMMEDIATE
INTEGRATION
NEED.”
3

4. THE REBOOT SKEPTICS
SKEPTICS IN THE INDUSTRY
WE HAVE THE BEST CAPABILITIES, SALES ENGINEERS CAN BRIDGE THE GAP IF A PARTNER NEEDS HELP
WE HAVE NEVER DEPRECATED AN API, WHAT SIGNAL WOULD IT SEND TO OUR EXISTING CUSTOMERS
SHOULD YOU NOT FIX THE BUGS THAT YOU HAVE INSTEAD ?
NO ONE WILL MIGRATE, ARE WE NOW GOING TO MAINTAIN 2 SETS OF APIS?
OUR COMPETITORS ARE NOT DOING IT,
IT WORKS - IF IT AIN’T BROKE DON’T FIX IT !
FEEDBACK IS POSITIVE (FROM THE BUSINESS PERSON) I SHOWED OUR API’S TOO, IT DOES EVERYTHING THEY WANT IT TO DO
WHY DID WE MESS UP IN THE FIRST PLACE?
PRIORITY IS TO LAUNCH A NEW MOBILE APP, AND OPTIMIZE OUR WEBSITE
4

5. HOW AN API PRODUCT MANAGEMENT PROCESS SHOULD BE
API PRODUCT PROCESS
5
DISCOVERY DESIGN DEVELOP DEPLOY & LAUNCH
Problem
Identification
Competitive
Research
Build Persona
User Research
Developer
Experience
Business Case
Development
PRODUCT
MANAGER
Define
API endpoints
Fields /
Objects
Documentation
Validation
errors
Mock Request
Response
API Specification
(e.g. swagger)
Iterate
PRODUCT
MANAGER
API
DESIGNER
ARCHITECT
LEAD
ENGINEER
Define
Backlog
Generate code
from Api spec
Security
Load &
Performance
Developer
Experience
Functional
Tests
Iterate
PRODUCT
MANAGER
API
DESIGNER
ARCHITECT
ENGINEER
ING
QA
Launch
SDK
Generation
User
Testing
Marketing
collateral
Integration
Guides
Monitoring
Training
PRODUCT
MANAGER
API
DESIGNER
ENGINEER
ING
QA
SALES
USERS
Webhooks
Sandbox

6. WORD TO THE WISE 6
SEEK OUT YOUR CRITICS
©RahulDighe

7. WORD TO THE WISE 7
DON’T LOOK BACK UNLESS YOU WANT TO GO THAT WAY
©RahulDighe

8. INCONSISTENCY ⍺ NO. OF TEAMS THAT WORK ON THE API
API FRAMEWORK/GUIDELINE
▸ Setup a framework / guidelines encompassing the
product life cycle:
▸ Design
▸ Develop
▸ Document
▸ Launch/Release
▸ Manage lifecycle, of your APIs
▸ If you do not have the resources to define your
own be inspired by others [https://github.com/
paypal/api-standards]
▸ Such approach provides guiding principles and
solutions, taking the mystery out of building API
products and make them more accessible.
8
©RahulDighe

9. API VERSIONING
VERSIONING POLICY
▸ Do you have a clear versioning
policy:
▸ that describes the product
evolution
▸ compatibility guidelines/principles
▸ EOL (end-of-life) policy
▸ Versioning guidelines for your
internal developers are exhaustive
than the public guidelines (do your
developers understand it?)
9
v {1} . {1}
v {1} . {2}
v {1} . {3}
v {1} . {4}
v {1} . {5}
External (v1) Internal (v1.x)
Major version Minor version

10. CORE PLATFORM PRINCIPLES AND API STANDARDS
▸ Every company should define the
core principles of an API platform.
▸ API standards are written around
the platform principles and provide
guidance to all stake holders.
▸ API standards define all patterns,
style guide, helps maintain
consistency, helps adhering to
company’s security policies,
versioning, backward compatibility,
lifecycle management etc.
ANY ORGANIZATION THAT DESIGNS
A SYSTEM (DEFINED BROADLY WILL
PRODUCE A DESIGN WHO
STRUCTURE IS A COPY OF THE
ORGANIZATION’S COMMUNICATION
STRUCTURE
10
API STANDARDS & PLATFORM CAPABILITIES
IDENTITY CHECKOUTPAYMENTS
CREDIT INVOICING
BILLING
COMPLIANCEWALLET

11. SUPPORTING ORGANIZATION ADOPTION
TOOLS & PROCESSES
11
Dev Frameworks
Spec to Code
generation tools
Contract vs
implementation
verification
Educate & Train
on API Design
Centralized API
Repository
API Maturity
Model
Common objects/
capability model

12. TRY NOT TO SURF IN CALM WATERS
TIMING IS EVERYTHING
▸ Did you just take on a new role and
people are more receptive to hearing
new ideas from you?
▸ Is there a new leader that has joined the
organization that has a passion for APIs?
▸ Did one of your competitors just launch
an API that was well received by the
market?
▸ Company is in a growth mode and is
open to investment for a Proof of
Concept.
©RahulDighe
12

13. DOES YOUR API NEED A
REBOOT?
rdighe@paypal.com
@rahuldighe
National Museum of the USAF
jjena@paypal.com
REACH OUT, WE APIS & ARE HAPPY TO HELP