[APIDAYS24]Implementing API-First : Practical Insights for Streamlining Your API

We often oppose Code-first to API-first approaches. Most of the coders prefer the first one because it is more code centric, and the documentation is automatically generated.
In fact, the latter is often perceived by them as a "boring-documentation-first" development.

However, the API-first design and implementation offer many benefits: streamlining your APIs, tackling the complexity and most of all, boosting the developer experience of your customers.

Through practical feedback we will cover how to implement API-first Approaches with the associated practices and tooling. We will then pinpoint the main difficulties to struggle with.

We will therefore see how to tackle this huge challenge: improve the quality of your API, increasing the adoption of your APIs by your customers, and most importantly, make your developers love the Documentation Code First approach!

Transcript

1. Implementing API-First : Practical Insights for Streamlining Your API Alexandre TOURET
3. Documenting our API ?
4. The documentation
6. Code- First API-First API-First to the Rescue
7. Alexandre TOURET Software Architect @touret_alex blog.touret.info alexandre-touret Who am I? @touret.info
8. We design payments technology that powers the growth of millions of businesses around the world. 7000+ engineers in over 40 countries Managing 43+ billion transactions per year €250M spent in R&D every year Handling 150+ payment methods #1 European payment processor
9. A customer point of view
10. The « 3-Five rule » 5 seconds to get into it 5 minutes to test it 5 hours to implement it
11. Valuable Credible Desirable Accessible Usable Findable Useful Empowering API with UX!
12. ✓Being rapidly engaged with your API ✓A smooth integration ✓Get examples and accurate error management Concretely… What it means for your customers?
13. The plan
14. For our customers • Provide a cohesive view • Facilitate the integration • Anticipate easily the new functionalities For us • Avoid contract errors during the implementation • Remove boilerplate and useless code • Streamline the development API as a Product: Our goals
15. • Pinpoint stakeholders • Define the API in a functional way first Organization first
16. • Define a set of standards & best practices • Ensure all the API work the same An API Contract API Consumer Provider Contract Contract Consistency is key
17. Standards • https://cloud.google.com/apis/design • https://jsonapi.org/ • https://docs.github.com/en/rest/about-the-rest- api/api-versions Style guide & standards • Who, How? Validation
18. Track & manage your API portfolio • The larger your platform becomes, the harder it gets to track API and their dependencies • Necessity to have a portal for internal developers
19. Tools https://tools.openapis.org
20. Store Store all the assets into a Git repository
21. Build Generate the changelogs Pinpoint blocking changes Generate code
22. Validate Use Merge request Include tools to the pipeline
23. Publish Publish the API 1. Internally • Portal using Docsy • Artifact repository (e.g., Nexus) 2. Externally
24. • Start validating your API first • Fix it if needed • Move it step by step to API First What about the legacy?
25. Revamping an application
26. https://github.com/alexandre-touret/apifirst-sample Example
28. Wrap-up
29. • Complexity of the OPENAPI specification • The migration of the legacy is complicated • Bugs & issues in the generated code Difficulties & Drawbacks
30. Stick to the specifications Better time to market Better quality Streamline development Benefits
31. • Guarantee the quality of your deliverables • The documentation is part of the deliverables! Developer Experience Think from the customer's point of view!
32. The function of good software is to make the complex appear to be simple. – Grady Booch
33. Don’t be a stranger! Follow & get in touch blog.worldline.tech @WorldlineTech Follow our tech team: Follow me: @touret_alex linkedin.com/in/atouret 33 | @touret.info @techatworldline.bsky.social
34. Explore our jobs in tech: careers.worldline.com Want to shape how the world pays and get paid?