The (really) long journey to an API Community of Practice in a 130 years old insurance company

Jérome Freyre — Thu, 20 Mar 2025 07:33:34 +0000

The Early Days: A really small IT Team 🧑‍💻

The long journey we're going to present began in the 70's with a small team of three people that were representing the whole IT department of Vaudoise Assurances. Since that period, IT continue to grow and grow and build a huge complex transactional system based on cobol still used today.

Discovering the Chaos of APIs in 2015 🌪️

In 2015, a group of fresh developers joined the Vaudoise Assurances and started exploring APIs unfortunately only to find a chaotic landscape. As the IT Department grew to more than 200 people, we faced the challenge of managing the legacy world while embracing new technologies. Long story short, each team was creating their own APIs for their own needs, leading to duplication and inconsistency. Data was copied multiple times (the worst case identified was 14 times 😱), and there was no standardization in naming (mix of french and english) and documentation. Result: It was a nightmare for developers and consumers alike.

Building the Community of Practice (CoP) 🤝

Determined to bring order to this chaos, we started creating a basic set of API guidelines within their own unit. This was a small but significant step towards consistency. However, the real breakthrough came when the company's top management decided to undergo an agile transformation, adopting the SAFe framework ( which was later abandoned, but we kept the core concept). This framework emphasized the importance of Communities of Practice (CoP), and we saw an opportunity to formalize our efforts. We created a dedicated wiki space, organizing meetings, and setting up communication channels. Our CoP was inclusive, allowing anyone in the company to join and contribute. We categorized members into different groups based on their level of involvement, from transactional to core team members. In the very first days of the CoP, we had tons of meetings about organisational and technical stuff like paging, caching, logging and many other topics. We were continuing to establish our standards API.

Continuous Improvement and Adaptation 🔄

In 2019, we've also been able to define a strong new process of API review before implementation that force people to share their Open Api definition before coding any line of code. Since that time, we've conducted more than 400 API design reviews before implementation, ensuring quality and consistency. 🚀

Building the CoP has been an ongoing daily effort, requiring continuous communication, training, and adaptation. But we were committed to this cause because we strongly believe in the power of community and the value it brings to our company. To achieve this, we started by engaging with IT management. We asked for freedom for technical leaders, legitimacy for our CoP, and ongoing support. This allowed us to create a recognized and respected group within the company. We also reached out to product owners, explaining the long-term benefits of standardized APIs and gaining their trust and support. For developers, we communicated the existence and importance of the CoP through various channels, including town hall meetings and blog posts. We organized training sessions, both optional and mandatory, to ensure everyone was on the same page. 🎁📆 Fun events, like an advent calendar with daily API questions and prizes, helped to keep the community engaged and motivated.

At the beginning of 2025, we have more than 25 members in our CoP, with our guidelines publicly available on our GitHub account and almost 70 internal APIs adhering to these standards. Since 2019, we acknowledge that the CoP has become less active over time, as the standards are now well established, with only minor updates being published.

The key to our success has been constant communication and a bottom-up approach. Natural leaders emerged within the CoP, driving the initiative forward with passion and dedication. We also received crucial support from management, which helped to legitimize our efforts and ensure compliance with the guidelines.

Our strategy was to provide clean, consumer-friendly APIs, even if the backend remained messy. Over time, we aimed to improve the backend as well, but our priority was to ensure a positive experience for API consumers. This approach allowed us to gradually build a solid foundation of standardized APIs while managing the legacy systems.

As we continue this journey, we remain focused on our goals. We know that building a CoP is an ongoing process that requires perseverance and adaptability. But we are confident that our efforts will lead to a more efficient and cohesive IT environment, benefiting the entire company.

So, if you're facing similar challenges, remember that transformation is possible. It takes time, effort, and a lot of communication ⏳💡📣, but the results are worth it. Join us in building a better future, one API at a time. 🥇

Design System : Kesako ?

Jérome Freyre — Wed, 26 Feb 2025 08:51:34 +0000

In the world of frontend development, ensuring a consistent user interface is crucial to delivering an exceptional user experience. Have you ever used an application where every page felt like it was designed by a different team? Buttons with varying styles, inconsistent colors, and an overall fragmented experience? This is exactly what a Design System aims to solve.

What is a Design System?

A Design System is a structured set of rules, components, guidelines, and design principles that ensure visual and functional consistency across one or more applications. It goes beyond a simple component library by incorporating design guidelines, code specifications, and brand values. In short, it is a comprehensive guide to building seamless and effective user interfaces.

Why implement a Design System?

1. Consistency

A Design System ensures that the user interface remains uniform across all pages and features of your application. This allows users to navigate seamlessly, encountering familiar and predictable elements at every interaction. It also guarantees consistency even when multiple teams develop different parts of the application.

2. Boosting Developer Productivity

With pre-designed components and clear design guidelines, developers save time and effort when creating new features. This accelerates the development process while maintaining high visual and functional quality. For example, each team doesn’t need to reinvent and test their own buttons while ensuring they align with the Vaudoise brand identity.

3. Improved Collaboration

A Design System serves as a shared foundation for design and development teams, fostering better collaboration. It minimizes misunderstandings and aesthetic inconsistencies, creating a smoother workflow and a more unified product.

Key Elements of a Design System

📌 🎨 Color and Typography Palette
A reference for colors, fonts, sizes, and other design attributes that reflect Vaudoise’s visual identity.

📌 🔧 Reusable Components
A shared library of standardized components such as buttons, forms, cards, etc., ensuring visual harmony across applications.

📌 📏 Design Guidelines
Clear instructions on how to use components, colors, and typography consistently across applications.

📌 📄 Technical Documentation
Detailed guidance for developers on how to correctly implement each component and adhere to design principles.

📌 📈 Scalability
Designed to remain relevant and effective in an evolving environment while supporting continuous product and team growth.

📌 🔄 Process
A structured workflow for creating and updating components based on real needs and feedback.

What does it look like in practice?

Before sharing our own implementation at Vaudoise Assurances for our customer-facing frontends and what we've faced off (note: the website is not yet migrated 😇), here are some well-executed public design systems worth exploring:

Most of the examples above are open-source, so feel free to explore and get inspired! 😎

A well-implemented Design System is not just a time-saver for teams—it’s also a powerful tool for creating better user experiences. At Vaudoise Assurances, we’ve embraced this approach to ensure quality and consistency across our interfaces for the best customer experience. Stay tuned for more insights into our implementation! 🚀

DEV Community: Vaudoise Assurances