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

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

Transcript

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