apidays Paris 2022 - APIs the next 10 years: Software, Society, Sovereignty, Sustainability December 14, 15 & 16, 2022 API design best practices - a framework for building APIs as products Ryan Clifford, API Product Lead at Fiserv & Ros Bennis, Developer Portal API Product Owner at Fiserv ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

1. 1 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innova/ve Companies 2022
API design best practices
A framework for building APIs as products
https://fiserv.dev/
December 2022

2. 2023 SERIES OF EVENT
New York
May 16&17
Australia
October 11&12
Singapore
April 12&13
Helsinki & North
June 5&6
Paris
SEPTEMBER
London
November
15&16
June 28-30
SILICON VALLEY
March 14&15
Dubai & Middle East
February 22&23

3. 2 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
About us
Ryan Clifford
API Product Lead @ Fiserv
Ros Bennis
API Product Owner @ Fiserv
Visit our developer platform at fiserv.dev

4. 3 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
We are one of the largest merchant acquirers globally enabling payment
processing for instore and online payments
Nearly 6M
merchants
Nearly 10k
FI clients
Over 12k
transactions per
second

5. 4 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
API Product Framework
Design Building Launching Lifecycle Mgmt

6. 5 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore existing
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstraction
6. Structure the
endpoints and
resources
9. Comply with
linting rules
10. Create the
documentation
Designing

7. 6 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore existing
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstraction
6. Structure the
endpoints and
resources
9. Comply with
linNng rules
10. Create the
documentation
11. Mock the API
and validate with
client
12. Incorporate
feedback
Designing Validating

8. 7 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore existing
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstraction
6. Structure the
endpoints and
resources
9. Comply with
linting rules
11. Mock the API
and validate with
client
12. Incorporate
feedback
13. API design
review
14. Design
approval or
rework
15. Publish API
spec for early
access
Designing Validating Reviewing
10. Create the
documentaNon

9. 8 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore existing
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstracNon
6. Structure the
endpoints and
resources
9. Comply with
linting rules
11. Mock the API
and validate with
client
12. Incorporate
feedback
14. Design
approval or
rework
15. Publish API
spec for early
access
Designing ValidaNng Reviewing
10. Create the
documentation
13. API design
review

10. 9 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore exisNng
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstraction
6. Structure the
endpoints and
resources
9. Comply with
linting rules
11. Mock the API
and validate with
client
12. Incorporate
feedback
14. Design
approval or
rework
15. Publish API
spec for early
access
Designing Validating Reviewing
10. Create the
documentation
13. API design
review

11. 10 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
1. Review
guidelines &
standards
2. Define purpose
of the API
3. Understand
who the customer
is
4. Explore existing
APIs
5. Find reusable
data models
7. Create data
models
8. Design the logic
and complexity
abstraction
6. Structure the
endpoints and
resources
9. Comply with
linNng rules
11. Mock the API
and validate with
client
12. Incorporate
feedback
14. Design
approval or
rework
15. Publish API
spec for early
access
Designing Validating Reviewing
10. Create the
documentaNon
13. API design
review

12. 11 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Lifecycle Mgmt
Design Building Launching
Design Process
Headers, query
and path params
HTTP verbs Pagination Resource naming
Versioning,
sunsetting and
deprecation
Response codes Error messages
Filtering,
searching and
sorting
Payloads
Enums, field
formats and regex
Common
examples
Reusable objects Access privileges Security
Naming
conventions
Guidelines & Standards
Polymorphism
ISO and industry
standards
Webhooks and
events

13. 12 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Example 1 - Disputes API
Disputes (also known as chargebacks) occur when a cardholder wants to query a
transaction on their card statement. The card schemes (Visa, MasterCard & JCB)
provide a dispute process that allows transactions to be 'disputed' in cases of
fraud, incorrect processing or unknown transactions.

14. 13 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Disputes API
The Challenge
The Challenge – it’s complicated 😰

15. 14 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Disputes API
The Solution

16. 15 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Disputes API
The Solution

17. 16 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Documentation is key to a good developer experience

18. 17 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Example 2 - Transactional Data API
Transactional data is generated from taking and processing payments, mainly:
Authorisations – verifying a cardholder can make a payment
Clearing/transactions – formalising the authorisation into a transaction indicating
money is ready to move
Settlement/funding – moving the money from a cardholder to the merchant

19. 18 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Transactional Data API
The Challenge
The Challenge – relationships are hard 💔

20. 19 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Transactional Data API
The Solution
Before you would need to find the field to link to the next endpoint…

21. 20 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Transactional Data API
The Solution
But now we tell you the specific link (HATEOAS concept)

22. 21 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
You can also replace documentation by good API design

23. 22 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Example 3 - Checkouts API
During an online shopping experience our checkouts API steps in to redirect the
user to a Fiserv hosted payment page to take a secure payment on behalf of the
merchant (website owner)

24. 23 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Checkouts API
The Challenge
You can have an intuitive request body…

25. 24 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Checkouts API
The Challenge
And an even simpler response body…

26. 25 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Checkouts API
The Challenge
Even provide documentation

27. 26 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Checkouts API
The Challenge
The Challenge – But API design and documentaIon
doesn’t give the full DX 🤦

28. 27 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Checkouts API
The Solution – a real demo!

29. 28 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
So good API design and documentation paints the
picture, but a demo brings it to life!

30. 29 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Our framework provides the guide to designing
consistent APIs
Key Takeaways

31. 30 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Some APIs speak for themselves
(through API design)

32. 31 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Others need another voice
(via documentation)

33. 32 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
And some need a good demo

34. 33 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
BEST API REFERENCE DOCUMENTATION
WINNER 2022

35. 34 © 2022 Fiserv, Inc. or its affiliates. | FISERV PUBLIC
Recognized by Fast Company
World’s Most Innovative Companies 2022
Thank you!
Ryan Clifford
https://www.linkedin.com/in/ryanjamesclifford/
ryanjames.clifford@fiserv.com
Ros Bennis
h<ps://ie.linkedin.com/in/rosbennis
ros.bennis@fiserv.com