Finding your path. It’s something you hear everywhere. On LinkedIn, in podcasts, from your parents’ mouths. But nobody really tells you how it’s done. I don’t have the recipe either, but I do have my story. And if it can help even one person see things more clearly, then it’s worth telling.

My name is Almis, I’m about to finish my web developer apprenticeship at OpenClassrooms and, before getting there, it took me several years to understand one simple thing: the signals were there from the beginning, I just didn’t know how to listen to them yet.

Maybe you too, reading this article, are wondering about your current job, about a career change, about that little voice telling you something isn’t quite right, or on the contrary, the one that lights up when you touch on a specific topic. If so, I’m writing this article for you. Not to give you a miracle recipe (it doesn’t exist), but to tell you how I learned, at my own expense and through a lot of trial and error, to trust those signals.

The first ignored signal: the technical degree that didn’t suit me

Let’s rewind a bit. After my vocational high school diploma in Sales — a path I’d chosen somewhat by default because I liked interacting with people and because school and I, let’s say, never had a great love story — I left for England for almost a year. Language trip, odd jobs, expat life… It was eye-opening, but when I came back, I found myself facing the same question as before I left: what do I want to do with my life?

Without a clear answer, I did what many people do in that situation: I reasoned “logically.” I like math (without passion, let’s be honest), I like solving problems, I need a stable job, so why not a BTS in Public Works? The sector is hiring, it pays decently. And above all, above all, it would reassure my parents who were legitimately worried about seeing me drift without direction.

I’ll be honest: their criteria slipped into my decision without me really realizing it. Not through direct pressure, but through this visceral desire to stop seeing them worry, to give them a reassuring answer when they asked “so, what are you doing now?”

Off to Nantes, then. And there, from the very first weeks, a sense of unease started to emerge. Faint at first. I felt out of step with my classmates, two years younger than me. Then the signal grew stronger. My friends were moving forward with their studies, some were finishing their bachelor’s degrees, and I felt like I was eternally behind in a race I hadn’t even chosen to run.

Then it became impossible to ignore. I kept going to class, but my lack of interest grew every week. More than once, I turned around right when I’d nearly arrived, standing in front of the school’s door. My body was telling me something my head didn’t want to hear.

I eventually dropped out. At the time, it felt like a failure. Looking back, it was probably the first time I really listened to myself.

The blurry period

Then came Covid, lockdown, and the day jobs to make ends meet. Rent had to be paid, I wasn’t living with my parents anymore, and life doesn’t stop just because you’re searching for your path. In my story, this period might look like a gap. But the truth is, it taught me something precious: time spent searching is never really time wasted. Every experience, even the one that seems to have nothing to do with what you’ll do later, shapes the person you become.

I went back to school through a bachelor’s degree in Applied Foreign Languages with an international business focus. And there, unlike the BTS, I found subjects that genuinely sparked something in me: sales, marketing, fields that resonated with something deep within. I also discovered university life and made connections that, years later, turned into real friendships.

But something was still missing. The click wasn’t there.

The moment the signal becomes a shout

The click came from a completely unexpected place: a YouTube video. I stumbled almost by chance onto content from Benjamin Code, a developer talking about coding and building websites. I devoured his videos. And then, almost without realizing it, I started coding in the evenings, after work. My first local sites, my first lines that actually did something. I immediately loved the feeling of building something with nothing but a text editor and an idea.

For several months, I learned on my own. And eventually, the signal became so strong that it was impossible to ignore: I wanted to make this my career.

I signed up for a Ruby bootcamp at Le Wagon, geared toward career changers. Two intense months. And there, for the first time in my life, I understood what it felt like to wake up in the morning wanting to go learn. No more U-turns at the door. No more lack of interest creeping in. The exact opposite. People around me noticed it before I did: I wasn’t the same person anymore.

That was the signal I wish I’d recognized sooner. That energy that carries you instead of draining you. And the funny thing is, I’ve been passionate about tech since childhood. I always loved buying tech magazines as a kid, keeping an eye out for the latest tech. And yet I never followed that path, because of one thing: my prejudices and the things people said. I’d convinced myself that, to work in this field, you had to be a math genius, a geek glued to a screen trying to hack government websites. I never quite knew where those prejudices came from, they just stuck with me until I discovered Benjamin Code.

Finding my apprenticeship: patience as a strategy

After the bootcamp, the job market gave me a reality check: I didn’t find an apprenticeship or a job right away. But this time, it was different. Before, uncertainty paralyzed me. This time, I had a direction. A real one. And when you have a direction, uncertainty becomes just a fog to walk through, not a wall.

And then one day, I landed an offer at OpenClassrooms, the “Site du Zéro” of my childhood, the one I associated with a whole world of passionate geeks. Today, I’ve been there for two years as an apprentice, I’ve earned a bachelor’s-level degree in Symfony/PHP web development, and I’m working on projects that genuinely excite me. It’s only the beginning of my developer story, but it’s starting with a mindset I never thought possible a few years earlier.

A word for those who are hesitating

If you’re wondering whether you should change paths, I don’t have a universal answer for you. But I can tell you this: the signals you’re feeling deserve to be taken seriously. That Sunday-evening dread, that fatigue that has nothing to do with physical tiredness, that curiosity that lights up when you read an article on a particular topic… these are data points, your own desires. Not whims.

And to those who have people around them in the middle of searching, in the middle of a career change: help them. Not by telling them what to do, but by giving them permission to explore. We’re not born with a ready-made calling. We build it, through trial, error, and signals we’ve actually listened to.

I found mine in the end. And the feeling of doing a job you truly love, one I’m still discovering every day, is well worth the years spent searching.

Now, it’s your turn.

Learning to Trust Your Gut: How I (Really) Found My Path in Web Development was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

I often like to quote the famous saying, “It’s legacy.” In a company, those are the building blocks of a process or a product that nobody can really explain the origin of: when someone asks, “Why does it work like this?”, you can answer, “Ah… it’s legacy.”

At OpenClassrooms, as I imagine in the majority of companies, we also live with certain choices from the past which, although relevant at the time, don’t necessarily make sense anymore today. Those choices don’t make our day-to-day lives any easier, and we have to deal with them. One of our four core values at OpenClassrooms is “We Dare”. So, let’s dare to change.

The starting point: two coexisting GitHub organizations

Here is the technical context, which I won’t go into in detail in order to keep this article accessible to as many people as possible. Within our GitHub ecosystem, we have two different organizations. Organization A contains the source code repository for openclassrooms.com and all the associated continuous integration. All other repositories are in organization B. “It’s legacy.” The point of friction is that A’s CI needs workflows in B. Our talented DevOps therefore have to do gymnastics involving a GitHub App to make everything work properly. Besides that, those same talented colleagues have to manage the authorizations and other settings of both organizations.

To sum it up simply, we have a duplicate that has become unnecessary, but that sits at the heart of our school: our website. For years we’ve wanted to merge into a single organization, but there’s a risk because, I insist, it’s the heart of the online school.

A risk, precisely: what is it? Does it really exist, or have we simply been telling ourselves for years that there is a risk, but nobody can really say what risk it is? That last sentence is worth thinking about, because even risks can evolve and be reassessed. To get to the bottom of it, let’s look for the risks.

Analyzing risks and prerequisites

Before embarking on this migration, and despite the optimistic tone above, we have to seriously analyze the existing ecosystem. In the end, no major risk emerged. If this migration is carried out, we’ll need to update the repository URL in a few internal tools, evolve the continuous integration workflows, but nothing more — and nothing complex.

I’ll add a parenthesis here to clarify that all of this is true because, last year, a huge piece of work was done to overhaul our continuous integration. The entire infrastructure was modified and moved to Infra as Code, and continuous integration was migrated to GitHub. This recent work now gives us full mastery of the chain, and therefore a clear view of the risks. Without that prior work, the very idea of migrating organizations would probably never have emerged.

From preparation to execution

The key to preparation was bringing the right people together to successfully carry out the migration. We chose the date at the start of a sprint (a calmer period) and outside of vacation periods (to have as many experts available as possible). During the migration, there would be a code freeze on the repository, while the changes were made.

The day before, we had a moment of doubt and sweated a bit when a colleague raised a critical scenario: “Did you consider that if we change this URL here, then over there in the back on the right, it could make production disappear?”. They were right, but I told you above: the colleagues are talented. They found solutions and we didn’t need to postpone the planned migration date (we seriously considered it).

All signals are green, production is secured: so tomorrow morning, we migrate.

During the migration, one of the main technical challenges was handling the change of organization name in our environment deployment chain. Part of the system relies on that name (notably via Docker images), and if we modify only a single link, we risk “making environments disappear” — including in production — which was part of the risks identified upstream. Thankfully, everything had been anticipated and it went as planned. We still had to adjust what was missing on the new target GitHub organization side (environment variables and the GitHub App), and continuous integration gradually returned to normal, without a hitch.

The platform team and the principal engineer carried out the migration over half a day, as planned.

How does GitHub handle the migration?

The good news is that GitHub automatically handles the redirection to the new URL, as long as the old one isn’t reused for a new repository. In theory, there’s therefore almost nothing to change. Here are a few examples:

• A development environment doesn’t need to change the address of its remote (it seems appropriate to do it anyway).
• The Jira ↔ GitHub integration updated the URL on its own.
• Browser bookmarks still work.
• All the repository’s history and current state are migrated.

We ran into an issue with the indexing of past pull requests, so pull request search is broken. We opened a ticket with GitHub support, who handled this unexpected issue.

Everything related to the organization, however, will be lost in the repository: teams, secrets, GitHub Apps. All of that has to be recreated in the new target organization, or at the enterprise level, above.

What we take away

Some decisions were made for good reasons in the past, but as time goes by, knowledge grows and technologies evolve. As a result, decisions can be challenged — not for the sake of it, but to eliminate a point of friction. When a topic regularly comes back to the forefront as not being optimal, but we live with it, it might be the opportunity to question it with an overall, up-to-date perspective. The solution to the problem is sometimes not where we think it is, but perhaps two levels above. What matters is knowing what is really bothersome and what the ideal solution is, without setting technical constraints from the outset.

Zero risk doesn’t exist, but an analysis done with perspective and kindness can greatly reduce it. Having done this migration work in our team means that we can now start from a satisfying foundation to build our processes the way we want, without outdated technical constraints.

If you master the building blocks of your organization, don’t be afraid to challenge the status quo, without judgment, but with an open eye toward improvement and the future.

“It’s Legacy” isn’t an end in itself was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

This article is the direct continuation of Writing an Article in the Age of AI — Part 1: Is It Really Useful?
It is not necessary to have read the first part to read this article, but the reflection discussed there might interest you!

Congratulations! You’ve realized that you have experiences to share and you’ve motivated yourself to write an article. So you launch your favorite text editor and… panic sets in. The blank page. Your fingers refuse to move across the keyboard.

Wanting to write is the easy part! The hardest thing is to actually get started and begin writing.

If, as I often hear, you tell yourself “I don’t know how to write,” know that you’re far from alone. It’s not inevitable!

As we saw in the previous article, more than half of the content on the Internet today is not generated by humans. You might be thinking that you too could take advantage of new technologies, and in particular these two words: artificial intelligence.

It’s not necessarily a good idea.
Well… It depends on your approach. Let me explain.

The Mistake to Avoid: Making AI Your Author Who You Commission an Article From

The easiest thing would be to write a prompt to get your article in less time than it takes to say it. For example:

Write an article, ready for publication, about the importance of writing our own articles in the age of artificial intelligence.

As an anecdote, I used this prompt with Gemini and it generated this article. Only read it if you’re curious about the result (it only takes two minutes), but know that I didn’t edit anything at all: it was written 100% by AI.
I don’t deny it has qualities: it gets straight to the point, reads quickly, and explains concepts well. But its style is very standardized, sometimes even a bit clunky.

In terms of content, it barely scratches the surface of the subject.
In terms of form, it’s as if you’ve already read it.
It has no personality. Nothing truly original. Nothing creative.

In short: an article written entirely by AI has no soul.

Some will say that it’s enough to ask the AI to apply a particular tone, or even to copy the style of another author for the less scrupulous… The results might be a bit better, but the tone will remain generally very “mechanical.”

My way of treating the subject “Writing an Article in the Age of AI” is much more “human” in its form: I try to capture your attention, I adopt a generally light tone to make your reading flow, I address you directly as an individual reader.
I placed images from The Lion King to illustrate my points because I wanted to touch your nostalgic chord. Even if we don’t know each other, I know that we have in common this popular culture that speaks to us, humans.

Yes, the risk is that it won’t please everyone. At this stage of the article, if you’re still reading, it’s because you like my tone, and that’s great! But it’s indeed possible that I’ve lost quite a few readers who found my style a bit heavy-handed… And that’s too bad! (they’re missing out on a great article, so they’re the ones to feel sorry for, right?)

The advantage of AI’s sanitized tone is that it’s standardized to avoid raising eyebrows. It’s banal, but it’s neutral.
I deliberately chose an opposite tone to write this series of two articles.

For your own articles, there’s probably a happy medium to find.
And to do that, we’re going to use artificial intelligence.

The Right Approach: Making AI Your Advisor to Improve Your Article.

Whatever the field, asking AI to do all the work for you is generally a bad idea.
On the other hand, using AI to improve your own work — now that becomes interesting!

Start by structuring your ideas. If you’re not comfortable with writing, there’s no need to write prose: even simple bullet points are enough! You’ll ask an AI to format all that.
Start a conversation with your favorite artificial intelligence and give it the context of your project. For example:

I’m writing an article about {YOUR TOPIC}. Here are my ideas for the introduction: {YOUR IDEAS}.
Help me shape them into a smooth, reader-friendly introduction.

It’s a somewhat basic prompt, which you can refine according to your preferences, but it already gives good results!
That said, avoid simply copying and pasting the AI’s response. Rework it and constantly ask yourself the question: “Would I have said it like that?” Don’t hesitate to infuse your own tone and give personality (your personality!) to your article.
Never forget that: it’s your article. It should feel like it’s you talking to us, not a machine!

The best approach is to write as much as you can yourself and then ask the AI to improve what you’ve written. The most obvious is to detect mistakes: spelling or grammar errors are in trouble!

To go further, you can ask the AI to review the structure of a sentence to make the reading more natural.
Actually, that’s exactly what I just did for that last sentence!

Moreover, I didn’t take one of these suggestions as is: I rather made a mix between my original sentence and the different proposals. Don’t forget the essential: always make the AI’s response your own!

Artificial intelligences are also pretty good at translating text. If you want to extend the reach of your article, making a version in another language can greatly help!
The article you’re currently reading is actually an AI translation of this original french article. Pretty good, right?

So… What Are You Waiting For?

Whether it’s a child learning from their parents, a student guided by a teacher, or an apprentice trained by their peers, education is an integral part of our evolution. Human beings have always grown by sharing their knowledge and their experiences.

But — I’m repeating myself a bit but it’s important to remember — more than half of the content on the Internet today is generated by machines…

Isn’t that a bit worrying?
Are we ready to entrust new technologies with the generation of our knowledge?

It might be smarter to use these technologies to share even more. You have plenty of things to tell, and you now have the best tools to help you do it… so go ahead!

You just need to use artificial intelligence… intelligently.

And you’re capable of that, aren’t you?

Writing an Article in the Age of AI — Part 2 was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

Is It Really Worth It?

Of course! Here’s a structured, impactful article proposal, optimized for smooth reading. It adopts an analytical yet engaging tone, ideal for a professional blog, LinkedIn, or a specialized newsletter.

If you’re a human like me, congratulations: according to a 2025 study, you’re part of less than half of Internet traffic.

But more importantly, I imagine you’re rolling your eyes thinking something along the lines of:

What an idiot this author is, he just copy-pasted ChatGPT’s answer without even reading it.

Well, first of all, know that it’s not very nice to call me an idiot, but more importantly, you’re wrong! This article is indeed written by hand, by a real human, with flaws and a personal writing style. The opening line was just a joke — I’ll leave you to judge its effectiveness.
(To be 100% transparent: this article was originally written by hand in french, you can find it here, but has been translated in english with artificial intelligence.)

Let’s come back to that stat from earlier: more than half of Internet traffic is now caused by bots: AIs, automated scripts… in short, by things that aren’t really human.

This figure also applies to AI-generated content: our machines now create more content than we do.

So the question we need to ask ourselves today: what’s in it for me, as a human, to write an article?

What’s the Point of Writing an Article?

It’s very common to believe that writing an article is just about transmitting knowledge. While that is indeed one of the goals, fortunately it’s not the only one!

Writing an article is above all about organizing your own knowledge.

What is clearly conceived is clearly stated, and the words to say it flow with ease.
_ Nicolas Boileau

If you decide to write an article on a technical subject (for example, maintaining an API via OpenAPI), you’ll need to do a quick introspection of your own knowledge to make sure you don’t talk nonsense.

You’ll analyze what you know, you’ll research your topic, you’ll try to simplify your knowledge to explain it and write it down in black and white (or white on black if you prefer dark mode).

In short, not only will you transmit your knowledge, but you’ll also consolidate it.

If you ask an AI to write everything for you, this step will be completely lost, drastically reducing the value of the article for you.

Of course, don’t put words in my mouth: an article must also be valuable to the reader, it doesn’t all revolve exclusively around you!

If your goal is to be read, you’ll need to find a topic that can interest readers (and by “readers,” I mean “humans,” which seems important to specify nowadays…).

But I Have Nothing to Say! All Topics Have Already Been Covered!

You’re both right and wrong!

You’re right, because indeed all topics have been covered. Especially with AIs generating hundreds of articles per minute that all look the same.

And you’re wrong, because you do have things to say! Lots of them! And there is at least one topic an AI can never take from you: your experience.

If today explaining how to do something specific is no longer really useful, sharing your experience on various subjects has much more value.

AIs can write articles explaining complex concepts on the fly, sure, but they can never share their own feelings as well as we can. What’s more human than expressing your feelings about a lived experience?

This is what will set your articles apart from all those generated by AI. Your authenticity is now your added value.

And the best part: since it’s your experience, it will necessarily be unique. No one else could have written an article on this subject!

Have you implemented Clean Architecture in your company? Have you migrated a 15-year-old project to Next.js? Have you trained for a marathon even though you’re not an athlete? Have you taken on the challenge of giving up meat entirely?

No matter the subject: you’re probably not the only one in the world to have done it, but your experience, the challenges you encountered, and the lessons you learned from it are unique. And that might interest other people!

In short: you have things to say. So don’t hesitate, and do it!

OK fine, but I don’t like writing. I don’t have a “style,” I don’t know how to write an article properly.

Sometimes due to lack of time, often due to undervaluing their own writing skills, people who have experiences to share are very often those who don’t take the time to write them down.

If you’re in this situation and this article has motivated you despite everything to write your own, I invite you to check out its sequel: Writing an Article in the Age of AI — Part 2: How to Go About It?

Writing an Article in the Age of AI — Part 1 was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

Technology is everywhere in our daily lives. It shapes how we learn, work, communicate, and imagine the future.
Yet, for this future to truly reflect our society, it must be built by all talents, without exception.

As an Engineering Manager at OpenClassrooms, a mentor for the ElleStime collective, and mom of a teenage girl, this topic matters to me both personally and professionally. It is a major issue of equality and diversity for our industry.

Why this topic is personal to me

To begin with, I am a woman working in Tech. But this also takes me straight back to my time studying computer science at a technical institute. Back then, there were only a handful of women (literally!) in a class of around a hundred students.

We hoped our presence would help open the door wide for the next generation, and the women who came before us were hoping for the same thing.

And yet, as an Engineering Manager today, I still see middle school girls, including my own child, struggling with doubts about whether they truly belong.

This is one of the reasons why my involvement with ElleStime is so future-oriented.
We cannot settle for the status quo, especially when digital technology shapes every aspect of our society.

From 2010 to today: Understanding the past to shape the future

Looking back often helps us understand where and when things started to go wrong. Comparing today’s data in France with that of the 2005–2010 period highlights several turning points.

High School: A new challenge with early specialization

Around 2010
The proportion of girls in the scientific track (Terminale S) was steadily increasing, reaching around 45%. Access to science education was more general, and orientation choices left more doors open.

Today
With the introduction of specialized tracks, particularly NSI (Digital and Computer Science, only 15.2% of students are girls), students must choose their path earlier. This early specialization often leads young girls to self-select out of science, even before they’ve had the chance to fully discover their interests.
Early choices act as a filter, sometimes unconsciously discouraging talented girls from pursuing scientific paths.

Source: DEPP — French Ministry of Education

The Mathematics pathway: A key area to watch

Around 2010
More than 85% of students studied mathematics until the baccalaureate.

Today
Around 42% of girls choose not to continue studying mathematics between 11th and 12th grade.
This is a strong warning sign, as mathematics remains a major gateway to scientific and technical careers.

Source: “Femmes et Mathématiques” collective / Maths & Sciences collective

Higher Education: Stability that needs transformation

Around 2010
Women represented about 28% of students in engineering schools.

Today
The figure has risen to 35% across all STEM fields, a real but fragile improvement.
In “pure” computer science, however, female representation remains particularly low, at around 19%.

Source: UNESCO / CDEFI

The Professional World: A Talent Pool to Unlock

Around 2010
Women made up around 20% of the digital sector.

Today
While some roles are becoming more gender-balanced, strictly technical positions still stagnate at around 18%.
The potential is enormous: attracting more female talent to the core of tech means enriching the entire value chain.

Source: INSEE / Observatoire Femmes@Numérique

Why do teenage girls self-censor?

What I observe in real life is that the main barrier is not a lack of skills, but rather social and cultural obstacles:

• Lack of confidence and legitimacy
  “I’m not good enough at maths.”
• Persistent stereotypes
  The idea that “tech is for boys” settles in long before orientation choices are made.
• Fear of making mistakes
  Many girls hesitate to ask questions, afraid of appearing incompetent.

And yet, the curiosity, creativity, and teamwork skills required in our professions are already there.

The ElleStime experience: creating the spark

This is where initiatives like ElleStime come in.

This collective takes very concrete action by organizing one-hour sessions between teenage girls and women mentors from scientific and technical fields.

The goal is not to create an immediate vocation.
The goal is to make these career paths visible.

Because you cannot project yourself into what you cannot see.

When a student meets an engineer, a developer, a data scientist, and thinks:

“Oh… she looks like me. And she made it.”

Something opens up.

What really makes the difference

To truly change the game, we need to shift the way we talk about these careers:

• Value effort over “talent”
  Success comes from work and perseverance, not from an innate gift.
• Normalize the right to make mistakes
  Errors are part of the scientific process and of software development.
• Increase representation
  The more female faces we see, the more welcoming tech will feel.
• Connect tech to real-world impact
  Let’s show that technology is a powerful tool for solving societal challenges.

What can we do, concretely?

As Individuals

• Talk about your job
  Explain what you do in simple terms, without jargon: this is important to make your profession accessible.
• Encourage curiosity
  Support interest in science, even (and especially) outside of school.
• Question your own biases
  Stereotypes are often subtle, and unconscious.

Collectively

• Become a mentor
  Visit schools, share your journey.
• Support initiatives
  Engage your companies and networks with collectives like ElleStime.

Creating opportunities, not barriers

Words matter.
Role models matter.
Opportunities matter.

As parents, educators, and tech professionals, we have both the power and the responsibility to open doors.

Let’s not allow an entire generation of talent to miss out on Tech and Science simply because of a lack of confidence.
Let’s work together so that tomorrow, no young girl ever says:

“I’m not good enough for that.”

How to inspire the next generation of girls in tech and science was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

Oualid Abderrazek — Chief Product & Technology Officer

Abstract

Just as the “Mobile First” paradigm revolutionized product design and development by prioritizing the mobile experience, OpenClassrooms now stands at the cusp of a new era. Recognizing the transformative power of artificial intelligence in a rapidly evolving technological landscape, we are embracing an “AI First” approach to redefine online education, grounded in a strong ethical framework.

The Foundational Shift: From Mobile First to AI First

A little over a decade ago, the proliferation of smartphones and the surge in mobile internet usage gave rise to the “Mobile First” philosophy. This approach marked a significant departure from the earlier desktop-centric design, where mobile was often an afterthought. “Mobile First” compelled designers and developers to prioritize the mobile experience, acknowledging it as the primary mode of internet interaction for a growing number of users. This fundamental shift spurred several key developments:

• Responsive Design as a Standard: Websites and applications learned to adapt fluidly to various screen sizes and orientations, ensuring seamless accessibility across devices.
• Touch-Centric Interaction Models: User interfaces were meticulously crafted for touch input, replacing the traditional reliance on mouse clicks and enhancing mobile engagement.
• Performance Optimization for Resource-Constrained Environments: Recognizing the limitations of mobile processing power and bandwidth, performance became paramount, leading to the development of efficient code and optimized content delivery.
• Content Distillation and Prioritization: The smaller screen real estate of mobile devices necessitated a focus on delivering concise and essential information, leading to more impactful user experiences.

The “Mobile First” approach yielded significant benefits, including improved user satisfaction and engagement on mobile platforms, enhanced accessibility for individuals whose primary internet access was through mobile devices (bridging the digital divide), the emergence of new design patterns and UI/UX best practices tailored for mobile, and a substantial shift in development priorities with increased investment in mobile app ecosystems.

The Dawn of “AI First”: A Cognitive Transformation

Today, the technological landscape is once again undergoing a profound transformation, this time driven by the exponential growth and increasing sophistication of artificial intelligence. OpenClassrooms recognizes this pivotal moment and is strategically shifting towards an “AI First” approach. This is not simply about integrating AI as a feature; it represents a fundamental reimagining of how we design, develop, and deliver education, placing intelligent systems at the core of our strategy. This transition is fueled by several converging factors:

• The Data Deluge and Algorithmic Advancement: The unprecedented volume of data generated daily, coupled with significant breakthroughs in machine learning, deep learning, and natural language processing, now allows AI to extract meaningful insights and automate complex tasks with increasing accuracy and efficiency.
• The Democratization of Computational Power: The accessibility of powerful cloud computing resources and advancements in hardware have made it feasible to train and deploy sophisticated AI models at scale, democratizing access to advanced AI capabilities.
• The Rise of Personalized User Expectations: In an increasingly digital world, users have grown accustomed to personalized experiences and intelligent assistance across various platforms, creating a natural demand for AI-powered features in all aspects of their digital interactions, including education.
• The Strategic Imperative for Competitive Advantage: Businesses across industries are recognizing the immense potential of AI to drive efficiency, foster innovation, and gain a crucial competitive edge. For OpenClassrooms, embracing “AI First” is not just an option but a strategic imperative to remain at the forefront of online education.

Key Differences and Synergies: Navigating the New Paradigm

To better understand this transition, it’s crucial to highlight the key differences and underlying synergies between “Mobile First” and “AI First”:

Despite their differences in primary focus and driving forces, both “Mobile First” and “AI First” share fundamental similarities:

• User-Centricity as a Guiding Principle: Both approaches place a strong emphasis on understanding and meeting the evolving needs of the user as the cornerstone of successful product and service development.
• Strategic Transformation as a Catalyst for Growth: Both represent a fundamental shift in how organizations design, deliver, and experience their offerings, driving innovation and creating new avenues for growth.
• Disruptive Potential to Reshape Industries: Both mobile technology and artificial intelligence possess the power to fundamentally alter industries and reshape user behaviors on a massive scale.

In essence, “Mobile First” was about optimizing for a specific device and the user experience within that context. “AI First,” however, transcends device-specific considerations. It’s about optimizing for intelligence, leveraging AI to enhance every facet of the user experience and streamline business operations, regardless of the device or touchpoint. This represents a broader, more pervasive, and ultimately more transformative strategic shift. Artificial intelligence is rapidly becoming an indispensable element across our organization, influencing product management, development, marketing, and operations. Embracing this technology is not merely about accelerating existing processes; it’s about unlocking new avenues for innovation and establishing a distinct competitive advantage.

Why “AI First” for OpenClassrooms?

• Hyper-Personalization: At its core, “AI First” allows us to move beyond simple accessibility and digitalization towards true personalization of learning experiences. Imagine a learning journey tailored to each individual’s unique needs, pace, and learning style. AI has the remarkable ability to learn from user behavior in real-time and dynamically adapt content, flow, and even pedagogical approaches to create truly individualized experiences. This places the learner at the very center of every scenario, feature, and interaction, something that cannot be achieved without the adaptive intelligence of AI.
• Accelerated Innovation: AI empowers us to optimize our development and delivery cycles significantly. By integrating intelligent systems into discovery, competitive analysis, and market research, we can gain insights with unprecedented speed and accuracy. This enables us to define effective solutions and respond to evolving needs with greater agility and reactivity.
• Differentiated Experiences: AI fuels our capacity to develop solutions that not only address current needs but also proactively anticipate future user expectations. From sophisticated predictive models to intelligent automation, AI offers a wealth of opportunities to craft unique and deeply personalized educational experiences that set OpenClassrooms apart.
• Operational Excellence: In crucial areas such as implementation, delivery, and daily operations, AI algorithms can streamline workflows, identify and reduce inefficiencies, and ultimately free up valuable time and resources that can be reinvested in innovation and enhancing the learner experience.

The time for deliberation is over. The integration of AI is not a future aspiration but a present reality. At OpenClassrooms, we are already leveraging its power in areas like auto-orientation, CV and cover letter generation, learner-mentor matching, adaptive learning sessions, our AI Companion, and student support, as well as within our learning program design and materials. The future we envision is rapidly becoming our present reality.

Ethics of AI at OpenClassrooms

Our journey into the age of AI is marked by rapid advancements, demanding that OpenClassrooms not only keeps pace but proactively explores and tests emerging trends. This exploration, however, must be firmly rooted in fundamental ethical principles. We recognize the significant ethical considerations that accompany the development and deployment of AI:

• Algorithmic Discrimination: AI algorithms can inadvertently perpetuate and even amplify existing societal biases present in their training data, leading to unfair or discriminatory outcomes.
• Lack of Transparency: The intricate nature of many AI learning models and the datasets they utilize often lack transparency, making it difficult to understand how decisions are made.
• Data Privacy: The potential for fraudulent use of personal data integrated into AI databases without proper consent or adherence to data subject rights is a critical concern.
• Violation of Copyright: AI training can inadvertently utilize content protected by intellectual property without the necessary permissions, leading to copyright and trademark infringements.
• Job Transformation: The automation capabilities of AI may lead to a mismatch between the existing workforce’s skills and the evolving demands of the job market.
• Excessive Surveillance: AI can be employed for intrusive monitoring of individuals, raising serious concerns about privacy violations.
• Increasing Environmental Impact: The computational demands of training and running complex AI models contribute to a growing environmental footprint, the full extent of which can be challenging to predict and control.

OpenClassrooms is steadfast in its commitment to the ethical use of AI. We are dedicated to ensuring that our algorithms strive for transparency, aiming for explainability and understandability in their operations. Responsibility is paramount; all the teams within OpenClassrooms are accountable for their actions and the outcomes of the AI systems we create and utilize. We are equally committed to equity, ensuring that AI is applied fairly and without discrimination, promoting AI for Good — the use of artificial intelligence for positive and ethical purposes, including fostering inclusion. Furthermore, we recognize the importance of environmental consciousness in our adoption of AI, striving for frugality and efficiency in its deployment.

To navigate these ethical considerations effectively, we are constantly monitoring and considering:

• Legal Compliance and Data Privacy: Rigorously adhering to regulations like the AI Act (with its risk-based approach) and GDPR principles, ensuring the lawful and privacy-respecting use of AI. This includes carefully reviewing partner terms, offering opt-outs for internal data training, and updating our own terms and contracts to reflect AI usage and protect user information and intellectual property.
• Transparency and User Rights: Providing clear information to users when AI is employed, especially in high-risk applications. This includes explaining the logic behind automated decisions, ensuring the ability for users to challenge these decisions and request human interactions, and facilitating the exercise of data subject rights.
• Fairness and Mitigation of Bias: Actively working to identify and mitigate biases in AI algorithms and training data. This involves incorporating diverse perspectives in AI development and rigorously testing for discriminatory outcomes, particularly in sensitive areas like education access and career services. We also recognize the potential of AI to promote inclusion by personalizing learning and supporting students with diverse needs.
• Education and Awareness: Empowering our students with the knowledge to understand the ethical implications of AI, encouraging critical thinking about its development and use, and preparing them for a future where ethical considerations in AI are paramount.
• Responsible Innovation and Environmental Awareness: Encouraging a mindful approach to AI adoption, prioritizing frugality and efficiency in its application, and considering the broader impact of our technological choices on human progress and the environment.

Towards a Responsible “AI First” Culture at OpenClassrooms

Building an “AI First” culture at OpenClassrooms, therefore, is not solely about technological adoption; it is intrinsically linked to fostering a deep understanding and commitment to the ethical principles outlined above. This means:

• Continuous Learning and Ethical Skill Development: Empowering our teams with AI fluency and a strong ethical compass through ongoing training, workshops, and knowledge-sharing initiatives that emphasize responsible AI development and deployment.
• Experimentation, Iteration, and Ethical Prototyping: Fostering a culture that encourages innovation in AI while embedding ethical considerations into every stage of the development process, from initial ideation to rapid prototyping and testing for potential biases and unintended consequences.
• Data-Driven and Ethically Informed Decision-Making Across All Departments: Embedding data analytics and AI-driven insights into our processes while simultaneously establishing clear ethical guidelines and review mechanisms to ensure responsible and fair application.
• Adopting a Future-Oriented and Ethically Conscious Mindset: Proactively exploring and integrating emerging AI technologies with a critical eye towards their ethical implications and potential impact on individuals and society. We must strive to be at the forefront of innovation while remaining deeply committed to building AI systems that are transparent, responsible, equitable, and environmentally conscious.

As we embark on this transformative journey, our commitment to an “AI First” strategy, guided by a strong ethical framework, will undoubtedly propel OpenClassrooms to new heights. This evolution will not only solidify our position as a leader in the online education landscape but also ensure that we create significant added value for our community of students and professionals in a manner that is both innovative and responsible.

Conclusion: Shaping the Future of Education Ethically, Intelligently, and Sustainably

The transition to an “AI First” strategy at OpenClassrooms is more than just a technological imperative; it is a strategic opportunity to redefine the future of education with intelligence, integrity, and a deep sense of responsibility. In a world where AI is rapidly transforming every aspect of our lives, OpenClassrooms is committed to a holistic and ambitious approach, infusing AI into the core of our product to deliver unique, deeply personalized, and adaptive learning experiences for every student and employer, all while adhering to the highest ethical standards. By embracing AI-driven innovation with a strong ethical foundation, OpenClassrooms can empower students, enhance accessibility, promote fairness, and solidify its position as a leader in the global education landscape, shaping a future where technology serves humanity in a responsible and sustainable manner.

Entering the Age of Artificial Intelligence was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

The purpose of this article is to share the initiative we have led in OpenClassrooms with security professionals.

Having a favorable context

2024 was the year of AI for most companies. At OpenClassrooms, we were working on integrating AI into our Product and Internal practices. As part of our activities, course creation involved the use of AI to streamline content creation, from writing to video and audio.

We explored a huge number of AI tools to help us in content creation. From a security perspective, our objectives were twofold: make sure we are using secure and securely configured AI tools, but also make sure we are using AI in an ethical and secure manner.

But what about a malicious threat actor using the same tools to perform an attack on the company? How easily can it be done?

With 90% of OpenClassrooms’ workforce working on AI-related topics, it was clear that we had to show how AI impacted Security threats. And what better way to illustrate that than by performing a fake AI-generated attack?

A full AI-generated attack

For this exercise we wanted to have the attack fully AI-generated. Few constraints we have defined, however:

• Phishing attack, targeting all OpenClassrooms’ employees. Indeed, like most of the Security team, we are performing regular fake phishing campaigns, and we wanted to “spice things up”
• Embed a convincing AI-generated video in the fake phishing email
• Use only publicly available information, to simulate a targeted external attack with no insider information

After brainstorming, the project was shaping: impersonate our CEO, as his digital footprint is large enough & we are frequently targeted by phishing attempts impersonating him.

And before doing anything, we asked for our CEO’s consent. It sounds dumb but without his permission, we would not have done the project. In addition it was a good way to involve him and raise awareness among the C-Team.

We followed the steps we believe an attacker could follow:

RECONNAISSANCE

1. Using Google with “OpenClassrooms”, we can easily find our co-founder and CEO.
2. On https://jobs.openclassrooms.com we can find that OpenClassrooms provides Swile cards to employees. In addition we can find the company’s values (for ex. CARE)

GATHER PUBLIC MATERIALS FROM OUR CEO

1. Find our CEO on YouTube.
2. Download CEO’s YouTube videos.
3. Download text transcripts of CEO’s videos from YouTube.

GENERATE THE ATTACK VIDEO

1. Train AI voice model using audio from videos.
2. Train AI video avatar model from video.
3. Use AI LLM (GPT) to write attack script.
4. Give transcripts to AI LLM to mimic CEO’s style.
5. Use AI voice model to make “fake CEO” read the script and get an audio file.
6. Use AI video avatar model to create a “fake CEO” video lip-synced to the audio file.

HOST THE VIDEO ON YOUTUBE

1. Create a new Google account for free, impersonating OpenClassrooms
2. Upload video using this account

LAUNCH THE ATTACK

1. Create a phishing email & landing page suited to the theme.
2. Include “fake CEO”’s video in the email.
3. … wait for the alerts to Security team 💪 or the clicks 😱

We only used legitimate and internal tools that have some safeguards, especially HeyGen (video avatar) and ElevenLabs (voice model), that attackers couldn’t have used as easily as us. For ex., to create an avatar in HeyGen, the “victim” needs to say a randomly generated sentence while looking at the camera.

However we believe that attackers have their own tools, just as convincing, without safeguards.

As OpenClassrooms’ security team, we were quite happy with the results

Coupling with a digital footprint masterclass

In addition to AI, this attack is also based on publicly available information about OpenClassrooms, our C-Levels and all employees.

Therefore we wanted not only to raise awareness about AI, Deepfakes and so on, but also about what remains in everyone’s control: our Digital Footprint

We completed the fake phishing campaign with a Digital footprint masterclass, where we demonstrated that, with publicly available information and some attacking methods, an attacker can use everyone’s digital footprint for malicious purposes. A few examples we demonstrated:

• Wrongly configured social network profiles that can leak personal information
• Fake friend request to gain access to personal information
• Using personal information to guess a weak password
• Risks of sharing too much information on social networks (date of birth, ID card, photo, etc.)
• Targeted spear-phishing using personal information to increase credibility
• Risks of having the same password everywhere, with no MFA

Finally, we gave key & actionable recommendations that everyone can apply:

LIMIT YOUR EXPOSURE

• Perform a regular auto-check Google search with your name, etc.
• Limit what and how you share on social media Who can see my activities? Can it be used against me?
• Review your confidentiality parameters on social media Who sees what from your profile, posts, etc.

APPLY SECURITY GOOD PRACTICES

• Ensure the MFA (multi-factor authentication) is activated on all your social media
• Respect password good practices Length & complexity, different for all your accounts, etc.
• Think about the “need-to-know” principle when sharing data with people or services Don’t hesitate to enter fake information / create a fake identity

CHOOSE WITH WHAT / WHOM YOU SHARE

• Limit the tracking Refuse cookies, use a VPN, etc.
• Avoid using free services with your personal data No guarantees in terms of security & privacy
• Regularly remove / uninstall tools that you don’t use

Key takeaways

The outputs and feedbacks we got were great:

C-LEVEL FEEDBACKS

• C-Level involvement was key to gathering consent but mainly to raising awareness of how easily an attacker can perform a realistic attack. Our CEO’s feedback on a specific sentence generated by the AI was “this is not realistic as this is something I would say internally but never externally, so an external attacker would not be as realistic as that”. Then we showed him with the prompt we used, and the publicly available data we gave as input. It was an eye-opener for him.

COMPANY’S FEEDBACKS

• When we sent the fake phishing email, it was a bit disappointing as some people quickly identified that it was phishing. And because we have put good phishing alerts foundations in place, the information was quickly spread across the company. But at the same time, we were not trying to do something hard to spot, we were trying to illustrate a new kind of attack, that can happen now based on AI accessible technologies. A new kind of attack.
• But people were intrigued: “How did you do that?” “Wow, this is realistic, and if others hadn’t warn me about it, I would have fallen for it” “I noticed this is a phishing exercise, but can we still click on the video?”. Explaining the making of the deepfake a day after sending it to all mailboxes was definitely a great idea: we explained our methodology, and it felt like this is now accessible to any malicious actor with no specific skills

COMPLETING WITH DIGITAL FOOTPRINT REDUCTION

• Completing the deepfake with a Digital Footprint masterclass was definitely a great idea. While the deepfake was impersonating our CEO, the pitfall would have been to think “I am not the CEO, no one will deepfake me or use publicly available information on me”. But really? Are you sure of that? Let us demonstrate what an attacker can do with all the information that is available about you. Controlling your Digital Footprint is key to avoiding fraud, account takeover, cyberbullying, etc. Demonstrating how someone’s Digital Footprint can be used against them made the topic more accessible to everyone.

In the end, we had a very good level of engagement to participate in the masterclass, and people were asking us a lot of questions. In addition, some people decided to take radical actions and drastically reduce their digital footprint (using GDPR requests to be forgotten and de-indexing from search engines).

Conclusion

When shaping the project, it felt like a crazy thing to do. When we started working on the project, we wondered “is it too ambitious?”. But when building concretely the attack and the digital footprint masterclass materials, it felt smooth and almost too easy to do. And when we delivered the attack and the masterclass, we had this “wow” effect.

At the end, it felt so impactful as everyone realized that “this is the world we are living in”, so let’s probably take appropriate actions now. It was an eye-opener for most of the employees. And we are proud to have triggered that.

How we deepfaked our CEO and received praise for it was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hi, OpenClassrooms IT & Security team here 👋. Today we want to present a key project we have done in 2024: Passwordless implementation.

We believe that traditional Multi-Factor Authentication (MFA) methods like passwords and Time based One Time Password (TOTP) are becoming increasingly inadequate against evolving security threats (MFA fatigue, no device security controls, etc.). The shift towards passwordless authentication, leveraging Device Trust and biometrics such as Touch ID on Mac, offers a more secure and user-friendly solution.

In this article, we will present our review of the internal multifactor authentication mechanisms to increase Security, simplify User Experience and better manage Enterprise hidden costs.

A bit of context

OpenClassrooms is a “Remote First” company, and it has a “Cloud Only” Information System. This is key for flexibility and modern efficiency.

To fit with this context, our Information System is composed of:

• A consistent device technology — Mac
• An Identity Provider — Okta, offering secure single sign-on capabilities to support our distributed workforce & applications
• A Device Management system — Jamf, ensuring all Macs are consistently updated, hardened and secured

Our MFA was relying on the following factors:

• Login & password
• TOTP or push notification on personal phone

Why is it not the most efficient MFA model?

This MFA model is clearly not the most efficient one in terms of Security and User Experience:

1 — Security

• Factors are not robust: password can be weak, stolen or guessable, and employees’ personal phones cannot be considered as secure and trustable
• These MFA are weak: Push notification is vulnerable to MFA fatigue, while TOTP is vulnerable to phishing
• We are not blocking employees or contractors to work on insecure devices (personal ones for ex.)

2 — User experience

• Password management is a pain point for users (expiration, complexity, etc.)
• When requiring personal device to authenticate, it means that you are blocked if your mobile is stolen or broken, and it requires users to have permanently their company device and personal device with them. And to accept the push notification, you need a password to unlock your mobile
• From a user point of view, division between professional & personal usage is unclear

From user experience, sometimes MFA feel like this: https://www.facebook.com/FallonTonight/videos/jimmy-tries-to-log-in-to-his-microsoft-account/331284788788842/

However it is widely used in companies. According to a short survey we have done when presenting our project to SecAtScale, a group of French Startup Security team, half of the companies have this MFA model, and the others benefit either from professional mobiles or hardware security keys.

We were not willing to deploy hardware security keys or professional phones, because that includes extra cost & effort to manage the additional factors and it was not solving all the above issues. Therefore we explored the implementation of a Passwordless solution, shifting from 2 “weak” factors (something you know & something you “possess”) to 2 more robust ones: something you possess (OpenClassrooms laptop) & something you are (Biometry)

Ok, so what have we put in place?

We have deployed Okta Fastpass to all Employees’ laptop.

It consisted in:

• Deploying Okta Verify Desktop (OVD) to all our Mac
• Coupling Okta & Jamf together, ensuring that Jamf is delivering the Device trust part, including the configuration of OVD, an SSO extension and a SCEP certificate configuration
• Enrolling all our devices to Okta Fastpass

In addition, we have deployed conformity checks on the device, for better security. Conformity checks include indication if the device has been jailbroken or not and OS version

Finally, we have implemented 3 types of Authentification policies, summarized by the below illustration:

What are the benefits?

This project is really a “must be done” project in our context, as it checks all the objectives of an IT department.

The benefits are summarized in this chart

1 — Improve Security

• Both factors are managed by the Company
• We enforce usage of Company’s laptops, on which we control the level of security
• We check the device compliance (OS version, etc.)

If you read Okta’s documentation, here is the scale of factor assurance, from lowest to highest level of assurance

2 — Better UX

• Moving from 30 secs on 2 devices, to 5 sec on 1 device
• Clear instruction on pro/perso usage

3 — Cost Optimisation

This is probably the less obvious criteria. It includes the cost of password expiry, the cost of ensuring continuous synchronisation between Okta and Jamf, the cost of people forgetting their password after vacation, the cost of dealing with a personal mobile stolen, etc. We had a certain amount of support requests linked to password management. And all the workload associated to these support requests has a cost for the Company.

Key success factors, from our point of view

We would not recommend this project for all companies context. However in OpenClassrooms’ context it made sense.

In our opinion, few key success factors must be present:

• Readiness of your tech stack: IdP & MDM supporting this technology (Okta & Jamf in our case). Single technology of laptops helped as well (Mac)
• Have a strategy for applications in pro/perso grey zone: what about the application allowing you to book a seat in a coworking space? Probably something where accessibility need is greater than security need, and therefore device trust might be an overkilling measure
• Have a strategy for contractors / temporary workers: indeed, as you are enforcing device trust to access the Information system, you need to provide a trusted device to your temporary workers. So do you really need to ship a Mac for a contractor working only for a week? The solution we found here is to rely on virtual desktop that are trusted, as a proxy to access our Information System from an unmanaged device. It is quite flexible & cost efficient, and user experience is acceptable

Conclusion

OpenClassrooms’ shift to passwordless authentication has significantly improved our security and streamlined the user experience, while also reducing operational costs. By deploying Okta’s Fastpass alongside Jamf, we’ve eliminated the shortcomings of traditional MFA, enhancing both security and usability.

And after one year of having it in place, we can confirm that the above benefits are real, and we are quite happy with it.

Related articles

• Okta Device Access with Jamf a step-by step guide
• Okta FastPass
• Managed devices
• Configure Okta as a CA with static SCEP challenge for macOS using Jamf Pro

Sick of Passwords? was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the previous article of this series, we shared our experience of using the OpenAPI specifications to document a REST API, and the issues we encountered (fast growing number of endpoints, and unmaintainable schema) and the solutions we found (leveraging the specifications to split our schema in small and manageable files).

In the second article of this series, I will explain what other uses of OpenAPI we investigated and implemented.

Automate, you will

Our backend engineers thought we could get more out of our OpenAPI definition. There’s always been a concern in our codebase about the complexity and number of files generated by our clean-architecture based approach. Why not use the OpenAPI schema to generate controllers on the fly, to perform request validation and build responses without adding unnecessary code files every time (especially these POPOs/DTOs) ? That’s what’s been quickly prototyped and it was a game changer.

The way this works is two-fold: we added a hook in the Symfony compiler pass, we use openapi-psr7-validator, to cache some request validators and routes. Then we created a generic OpenApiController class that allows to map all routes in the schema to a use-case class, using a specification extension property, which we called “x-usecase” and contains the FQDN of the matching PHP use-case class, that’s for each route operation definition. We still have some legacy routes that exist and are not covered by OpenAPI, so we have a bit of plumbing to detect those.

Now, not only can we document our API, but this schema can be used at runtime too, and saves us from writing boilerplate code !

Beyond documentation: API Tester

At one point, we thought we could still get more from the API documentation. Why not auto-generate some tests from the OpenAPI schema to add a massive test suite to our already existing unit and integration tests ? Once again, a core team quickly prototyped what became Api Tester.

This PHP-based tool loads up our OpenAPI schema, and generates thousands of tests automatically to hit our API with nominal cases (based on the examples in the documentation) and random tests to foolproof our API behavior and check all validators and security. A game changer once again.

Hopefully we’ll open-source API Tester in the future, if you want to know more, some of our team members presented a talk about this at the AFUP Day Lille 2023, a french PHP event, and we also participated in the Product Crew webcast for an episode dedicated to clean APIs and testing (in French).

Toolchain

Our toolchain goes like this:

• php-openapi (which we might replace with an OpenAPI 3.1 supporting fork in a near future), we use it to lint and also at runtime
• spectral, a CLI utility we use for linting with an added custom ruleset
• redocly to generate HTML documentation
• swagger-cli which we use both for a first linting pass, then to bundle our doc back to a monolith before passing it to Spectral, which does not handle references across files too good, but would like to do other things good too (bonus point if you get the ref).
• openapi-psr7-validator another great package by thephpleague

We recently found that the brilliant people at JoliCode have released a PHP library that can help leverage your OpenAPI schema to scaffold an API for you: check out Janephp.

Thoughts

Along the way, we encountered many issues, but we often found out that we were not alone. Browsing endless GitHub threads we ended up having the impression that the OpenAPI specs were great, with a cool community open to requests, but the ecosystem was lagging a bit, especially with PHP. Three years after the release of OpenAPI 3.1 in April 2021, which brings a lot of cool features, third party tools supporting this version are not the majority. You will encounter the same engineer names across many different discussions (kudos to them), and it seems the development of several widely used repositories is stalled, with no maintenance, forks ending up being created. But it’s open-source, so you can contribute. Anyway, https://openapi.tools/ is a great place to find tools and check which specs version they support.

The road ahead : API-First design

This OpenAPI schema overhaul was worth the work, we can now have validation on API endpoint creation, component sharing, easier git history on component creation, mocking, frontend uses also… Future plans include more custom linting rules, and further CI steps regarding validation and detection of breaking changes in the API. We still work on our API Tester too.

Some updates may be required to simplify the folder architecture though, as some developers think that we went a bit too far, there’s a trade-off to be made between reusability and ease of use (browsing the schema without a dedicated plugin in your IDE can be a pain, adding multiple files for an endpoint may seem overkill to some).

Managing versioning may also be on the horizon, but it’s a tricky subject.

But the major change is adopting an API-First Design approach, which we kind of partially do already, but this needs to be formalized into standardized processes; which might be the subject of a future post.

TL;DR;

The OpenAPI specification and the libraries that support it can be leveraged at runtime to generate controllers, validators and view models on the fly. We also developed a custom tool, Api-Tester, to automatically generate tests from the documentation.

Leveraging OpenAPI (Part 2) — Testing and automating your API was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.

Where we come from

First, a bit of context. The OpenClassrooms’ platform is built on a React stack in the frontend, and a Symfony PHP stack in the backend. Frontend uses the API that the backend exposes. The backend project also performs other tasks, but its main use is to expose the API.

We’re using the API internally, but we also have business customers who use our API to integrate our catalog into their platform, so the need for clean documentation is vital.

Also, we are adept of the “code documents itself” approach, and we enforce clean coding practices, and give a lot of importance to the readability of code and its reusability.

But at one point it became necessary for this 2012-started project to have some sort of API documentation. So a Swagger documentation was created. It was manually maintained and regularly out of sync. Some developers didn’t even know it existed and we had no real process around it.

Back in 2020, we decided to go for the OpenAPI specification instead and planned to build a schema for our API, which was already large with over a hundred endpoints. Manually creating the schema was out of the question. One of our senior engineers took the task to code a utility command (in PHP), to extract an OpenAPI schema from the code base. This was no mean feat, but once this was done, it unlocked many new possibilities.

Building a monolith

So, there we were with a 7k lines OpenAPI file, mostly auto-generated. It was not without issues. Auto-generation meant some fine tuning would be required to fix some readability issues, but still, it was solid enough.

We had a documentation now that could be used by our frontend engineers to refer to when we released new API endpoints, it could also be easily shared to quality engineers, managers, stakeholders, and to our business clients.

A couple of years passed, the company scaled-up, and here we were with 40+ engineers, multiple squads and teams, and new features on the platform arriving at a high pace, and by the end of 2022 we had about 240 endpoint definitions in our OpenAPI schema (and each endpoint often had several operations defined, as most CRUD endpoints do). It also contained 410 schemas and in the end it materialized as a single file of 32k lines, weighing 928 Kb, a YAML monstrosity. Once again, it became a pain to maintain, a pain to add endpoints, a pain to do code reviews on, a pain to refactor, a pain to just open in some editors which started to have trouble parsing it quickly. But we kept going.

Splitting the monolith

So, our OpenAPI schema became the brain of our API (more on that in the next part of this series). But it had become unmaintainable. Some errors and inconsistencies started appearing in the documentation. Engineers were copy-pasting components, it became messy.

We actually had a very basic knowledge of the OpenAPI specification at first. After a core team was dedicated to OpenAPI matters, focusing on learning more and more about the specs, we could finally see all that was wrong with our initial schema. We barely leveraged reusable models, we even didn’t use the requestBodies or responses components. Everything was schemas and paths. The external reference mechanism was barely used.

We had seen some nifty looking OpenAPI schemas, and we wanted to do something similar: have a main root file, and leverage the reference-to-file mechanism to split our massive file into hundreds of smaller, manageable definitions. This would open the path to better reusability. This would make code reviews much easier too. The tools were available to reassemble to a monolith if needed. And we were definitely not alone with APIs that large, APIs like those at Digital Ocean, or Box.com were a good source of inspiration.

Now, how could we split the monolith ? Refactoring manually was out of the question. Of course, we had done it before, we coded a tool to automate that !

Trials and tribulations

The initial proof of concept materialized quickly. Splitting into components based on the existing file was relatively easy. But we had a goal to not only split, but leverage the OpenAPI specification the best we could. This meant converting all the schemas to requests and responses based on heuristics, processing paths to extract url, header and query parameters… After a few weeks we were getting close, but our splitting command had itself outgrown the initial scope and it became much more complex. We had to refactor it. Cleaning the project allowed us to add new features much faster to our OpenAPI splitter, including detecting duplicate components, so that we could merge them into a single one. We could also detect unused models and remove them.

Early on we wanted to be sure that the documentation we generated was valid OpenAPI 3.0, so we went searching for a linter. The PHP library we use (cebe/php-openapi) includes a CLI validation command, so we tried that first. It worked to some extent, but it was very limited, and we soon found out that it did not pick up some errors, and would also pop up errors that were valid OpenAPI 3.0 declarations! We probably tested all OpenAPI linters then… and every single one of them we had an issue with. They would not even pop up the same errors on the schema.

As we already used Stoplight, we settled for Spectral as a linter, it was not perfect either, but we could start defining our own custom ruleset, and hope that the issues would be fixed in future releases. And… we had a bad surprise. Some valid OpenAPI definitions again wouldn’t work with Spectral, which was probably related to our heavy use of references and definitions across multiple files. Browsing dozens of threads on GitHub we found we basically all encountered the same issues, and found ways around the limitations, forcing us to add extra steps in our build and linting processes. In our case it was simple. We bundle back the files into a monolith before passing it to third-party tools, and it works better.

As things stabilized we had to tackle another big task we never thought would take so much time. Naming conventions (hey, Phil Karlton was right!):

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

As we were generating a completely new directory structure, with new files, for components that did not exist before, how should we name these so that it would be clean and meaningful to our engineers ?

Settling down

Well it took us quite a while, but we ended up writing lengthy guidelines describing naming conventions, and basically it ended up being a documentation on… how to write the API documentation. This file, as we do for all our ADRs, was committed to the project’s main repo.

Here we were, with a multi-files OpenAPI documentation. It was clean, not too much work was needed to make it work with other tools.

We had a branch with our new documentation, now was the time to merge it. The biggest challenges here were communication and planning. It took some preparation to not cause too many conflicts in our colleagues’ branches. We had to coach them on how to use the new documentation format and make sure our guidelines were known and adopted. We also ended up writing a small generator CLI command for engineers to quickly create all template files needed to define a new endpoint.

The process went well, of course we had to support the engineers for a few sprints through pair sessions, tutorial videos, and documentation, but it mostly went well with no performance impact.

We now happily work with an OpenAPI Schema which defines, at the time of writing:

• 324 paths
• 199 reusable schemas
• 173 request definitions
• 419 response definitions
• 212 parameters
• 105 tags

and it’s all built from 1338 files in a clear directory hierarchy. Hurray ! 👍

In the next part of this series about OpenAPI, we will talk about how we leveraged our OpenAPI schema to test our API and generate code dynamically.

TL;DR;

Our OpenAPI story began with the need for API documentation, leading to the creation of a Swagger documentation manually. In 2020, we moved to the OpenAPI specification with the help of a custom utility command which generated the schema from our PHP code base. However, over time, our initial 7k lines OpenAPI file became unmaintainable reaching up to 32k lines and 240 endpoint definitions, leading us to split our monolith, leveraging OpenAPI specification’s reference mechanism, which drastically improved reusability and eased code reviews. Although we faced many challenges during this process, including finding the best naming conventions and also the lack of support from the ecosystem, or the lag behind the latest official specs, we have found the end result invaluable for API-first design and validation. We definitely recommend splitting your OpenAPI schema to multiple files before the number of endpoints you have becomes too important.

Leveraging OpenAPI (Part 1) — Creating and maintaining your API documentation was originally published in Product, Experience & Technology @ OpenClassrooms on Medium, where people are continuing the conversation by highlighting and responding to this story.