apidays Paris 2022 - API design best practices, Ryan Clifford & Ros Bennis, Fiserv

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

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

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

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

API Product Framework
Design Building Launching Lifecycle Mgmt

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

6 © 2022 Fiserv, Inc. or its aﬃliates. | FISERV PUBLIC
Lifecycle Mgmt
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

Lifecycle Mgmt
Design Process
1. Review
guidelines &
standards
2. Deﬁne 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

Lifecycle Mgmt
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

Lifecycle Mgmt
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
10. Create the
documentation
13. API design
review

Lifecycle Mgmt
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
10. Create the
documentaNon
13. API design
review

Lifecycle Mgmt
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

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.

Disputes API
The Challenge
The Challenge – it’s complicated 😰

Disputes API
The Solution

Documentation is key to a good developer experience

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

Transactional Data API
The Challenge
The Challenge – relationships are hard 💔

The Solution
Before you would need to find the field to link to the next endpoint…

The Solution
But now we tell you the specific link (HATEOAS concept)

You can also replace documentation by good API design

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)

Checkouts API
The Challenge
You can have an intuitive request body…

Checkouts API
The Challenge
And an even simpler response body…

Checkouts API
The Challenge
Even provide documentation

Checkouts API
The Challenge
The Challenge – But API design and documentaIon
doesn’t give the full DX 🤦

Checkouts API
The Solution – a real demo!

So good API design and documentation paints the
picture, but a demo brings it to life!

Our framework provides the guide to designing
consistent APIs
Key Takeaways

Some APIs speak for themselves
(through API design)

Others need another voice
(via documentation)

And some need a good demo

BEST API REFERENCE DOCUMENTATION
WINNER 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@ﬁserv.com

apidays Paris 2022 - API design best practices, Ryan Clifford & Ros Bennis, Fiserv

More Related Content

What's hot

Similar to apidays Paris 2022 - API design best practices, Ryan Clifford & Ros Bennis, Fiserv

More from apidays

Recently uploaded

apidays Paris 2022 - API design best practices, Ryan Clifford & Ros Bennis, Fiserv