You don’t often get to meet a co-founder of a startup that follows, by all means, the “perfect successful startup” path. And by “perfect startup”, I mean the kind of startup that goes by the book. And by “the book”, I mostly mean Paul Graham’s essays.

I met Alexandre Lebrun, co-founder of Wit.ai, an AI platform that makes it easy for developers to create apps that users can talk to. He holds a degree from a top engineering school. He started his startup while he was living in Palo Alto. He had previous experience in the field. He built the app and launched it early on Hacker News. The app got traction. The team got into Y Combinator. They raised $3M after the Demo Day, with one of the most prestigious VCs (Andreessen Horowitz). 9 months later, they got acquired by Facebook.

Here you go. Perfect startup story. What is even more surprising is that when I asked Alexandre: “Your startup seems to be super successful from day 1, is that so?” his answer was:

“Well… yes”.

Don’t worry, there is a “but”

I was more looking for a “don’t be desperate, there are downsides behind all this, success never comes without struggle” kind of testimony. In reality, Wit.ai does indeed follow the success path from day 1, but it’s only because Wit.ai is Alexandre’s second startup. The story of his first venture, VirtuOz, involves many more mistakes that he learned from.

Doing things right the second time around

The story of Alex as an entrepreneur started in 2002, when he decided to launch VirtuOz in Paris. As an engineer passionate with voice recognition and artificial intelligence, his dream had always been to make robots understand human language. Inspired by chatterbots’ pioneers like Joseph Weizenbaum — who created ELIZA in 1966 — he imagined a solution much similar to Siri. Back in 2002, building Siri was impossible, both from the technological and business perspective. Right after the Internet bubble burst, he decided he would focus on a more profitable venture, and started VirtuOz as a virtual assistant technology for businesses’ customer service.

Alex Lebrun’s first startup VirtuOz’s story (and struggle)

It took VirtuOz’s team 3 whole years before landing their first client, in 2005: VoyagesSncf.com, the biggest online travel agency in France. It was their lucky year: they also raised $1,6M. In 2007, they decided to move to the U.S to explore business opportunities as they realized the French market was too small — the tech team remained in France. They soon realized that selling a product to AOL, Ebay, and other big players required much more than a nice product: you need to have a local data center, a 24h/24 customer support, huge sales teams, etc.

Nevertheless, VirtuOz managed to raise a round of funding of $12M in August 2008 — literally days before the fall of Lehman Brothers — with Silicon Valley investors. Because the new company’s scale required more structured operations and financial reporting to investors, and because Alex felt more like focusing on the product, he decided it would be wiser to hire a “professional” CEO.

His feeling was that the “Eric-Schmidt model” at Google was a smart one and that they could make it work at VirtuOz. He ended up realizing that what works at Google doesn’t necessary elsewhere. There was a huge mismatch between the newly appointed CEO — and the VPs brought along — and the rest of the team, in terms of culture and product understanding. As VP of Advanced Technology, Alex realized that he was no longer in power and did not feel he belonged within his own company — he took a year-long sabbatical, after which the board re-appointed him as CEO, in June 2012.

In the meantime, the culture had already changed and what he left a “startup” had turned into a 70-people company selling enterprise software. Alex decided to reorganize the team and launch a new product which ultimately lead him to sell VirtuOz to Nuance Communications in January 2013.

After the acquisition, and after he made sure the transition went smoothly, Alex went back on track and decided to launch a new venture, focusing on an issue he witnessed: on the one hand, there was a huge demand for machines’ comprehension of human language (written and spoken), on the other hand, there were only custom solutions made for big companies (with big costs). What is there were an API for developers that could give them the capacity to understand human language?

“After selling VirtuOz, I felt nostalgic of the “garage” period and decided to launch a new startup”

After spending ten years building and growing VirtuOz, Alex launched Wit.ai — a fully open API for voice recognition and language understanding, based on machine learning, and inspired by open models like Stripe and Twilio. He started coding it with his co-founder Willy Blandin in April 2013. Wit.ai was acquired by Facebook in January 2015. Here are a few things that helped making things right the second time around.

Spending time in non-important stuff VS building a product

The first thing that Alex did completely differently is that he did not spend a second on unnecessary tasks. He and his co-founder spent 6 months coding, period. Their company was not incorporated, had no office and no money, even when they applied to Y Combinator.

In his previous venture, Alex had lost an incredible amount of time in paperwork, renting offices, trying to raise funds before even having a single client — a mistake he would not replicate.

Similarly, he had waited much too long for a perfect product before looking for his first users. With Wit.ai, he forced himself — and his co-founder — to launch the product as soon as possible on HackerNews. It was an alpha version, far from what they would be satisfied with, but it was operational.

“It was a struggle to overcome the feeling that our product wasn’t ready before launching on HackerNews, but I knew we needed to confirm there was a need for our solution as early as possible”.

Wit.ai remained on HN’s homepage #1 position for 24 hours and they became a small phenomenon in the Valley. By the time they applied to Y Combinator, they already had 3,000 developers using the API.

Doing Enterprise Sales from the start VS Focusing on SaaS

When building a SaaS product, it is very tempting to sign major contracts with big players early on: it gives financial comfort, you feel it gives you business legitimacy, and it’s kind of flattering. That’s what Alex did with VirtuOz, and he learned not to do it again: when your SaaS startup is still young, you need to focus on building your own product. Larger accounts will ask for many custom features, a fully dedicated account manager, and ultimately distract you from building a scalable product that can be used by anyone.

That’s why when Wit.ai launched and Alex got meeting requests from big players, he refused in order to focus on building his product. With VirtuOz, he spent entire days with tech consulting firms without making a single dollar. With Wit.ai, he would rather debug 1 indie developer on the other end of the world for hours if it meant making the product better, than working with a multi-national.

“If you can afford to say “no” to big clients and partnerships, i.e. if you don’t have investors’ pressure or huge costs, and if you want your product to be used by the many, I’d say don’t sign the big contracts and focus on building a scalable startup.”

Alex was so convinced of his vision that he wanted to build a startup truly used by millions that he would rather fail than becoming a consulting business for big customers. According to him, time is an entrepreneur’s most important asset: if you develop fast, you can take greater risks — funnily enough, “Fail fast” is one of Facebook’s mantras.

Launching a startup in France VS San Francisco

Surprisingly — for me! — Alex remains pretty certain that you can start your startup from anywhere and do not need to be in the Valley from day 1. According to him, it’s all a matter of personal context. He could never have started VirtuOz in the U.S in 2002, and launching in France had its advantage at the time: he was able to raise €100k with family and friends, which would have been impossible in the Valley. The recruitment was made much easier, especially for tech profiles.

When he launched Wit.ai, he already was in Palo Alto, which of course, also had its advantages. For instance, when he launched on HN, he asked in the comments if anyone could welcome him and his co-founder to their office, as they were working from home. 10 min later, the founder of Pebble offered them 2 desks, to use Pebble’s office, network, snacks, meeting rooms etc. for free, and Wit.ai stayed there for 6 months, up until it was a 6-engineer company!

There are many tactical mistakes you can make when your startup has offices both in the US and France, says Alex. For instance, having a modern, powerful teleconference system in every meeting room is key. It’s also important to have people from both offices travel to the other office from time to time, in order to build personal relationship that will prove important in stressful times. But these tactical mistakes don’t impact the broader vision.

From those lessons learned, Wit.ai followed an impressive path of growth and ultimately got acquired by Facebook. While Alex was constantly refusing meetings with the corporate development teams of potential acquirers, when David Marcus (i.e Facebook Messenger lead and previously CEO of Paypal) contacted him, he accepted the meeting, which led to the deal. For Wit.ai, Facebook was a great opportunity to work with an incredible A.I research team, great resources, and a much larger scale, says Alex. The acquisition was announced on January 5, 2015, and Alex has since remained head of Wit.ai which still exists inside Facebook, with a team of 10 engineers. They strongly contributed to the debut of “M” last August, and will continue to work on Facebook’s A.I projects.

When you look at the story of Wit.ai in hindsight, the crazy 21-months startup success took Alex a decade of entrepreneur experience — and a great co-founder, he adds — to build. It is because Wit.ai is a product built by expert founders, passionate about their fields, who put their product in the hands of users very early on, and solved a real issue, that it was so successful.

Thanks Alex for this great lesson of humility and hard work!

This article is part of the publication Unexpected Token powered by eFounders — startup studio building SaaS startups. We have a very cool Hacker Program, learn more and apply here.

The (perfect) startup story of Wit.ai, acquired by Facebook in 21 months was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

You gotta love technical challenges

“When we developed Mention, our main competitor was Google Alerts, which feels a little like being David versus Goliath at first. But then it became one of the reasons I like my job: it is very challenging. Getting to this point of a product development involves a true entrepreneurial mindset. Before being Mention’s CTO, I was a developer and then the lead developer working on the media monitoring feature at Pressking. eFounders offered me to become Mention’s co-founder. I might not have thought of myself as an entrepreneur before, although today, I really feel like Mention is my product: I’ve built it together with my co-founders.

Building an application like Mention is full of technical challenges. We handle a large amount of data, crawl thousands of web page per second, built an open API for our own apps, and use lots of third-party APIs.”

FOCUS: a challenge overcome when developing Mention’s web crawler Since Mention crawls a large amount of web pages in parallel, there is a point when the crawler reaches a high concurrency level and stresses the OS: that is when we got to the limit of our system. In our case, these limits entailed the appearance of a race condition in the libc’s DNS resolver. libc was sending over DNS queries on random unrelated file descriptors, which was leading to weird behaviors. The bug was reported and fixed a few months later, but in the meantime, we had to use the plain-Go DNS resolve, which happened to work really well.

“At Mention, several millions of Mentions are inserted in user feeds per day (see infographics above). Therefore, storage of data is an important issue with our product and entails. We chose MySQL as our main storage system, which is well understood and scalable. We are also using Redis, as a cache, and Kafka for messaging.”

FOCUS: Mention’s main storage runs on Percona MySQL servers:

MySQL servers have a small layer of SSD caches (using flashcache)

Incremental backups using Percona Xtrabackup

Backups automatically checked everyday (loaded in a mysql server, queries ran against it)

Sharding for horizontal scalability

Sharding is done at the application level

Replication for high availability

Applications never read on slave servers — eventual consistency makes code eventually complex

Occasionally using slaves for large queries, dumps, etc

One of the shard groups stores 4.5B rows, 5TB of compressed data

Redis for small caches or data structures

40-nodes Cassandra cluster for the Crawler’s internal state

“Building a product that works in the long term is key to success, according to me. That is why we focused on that from the beginning, especially in the choice of our technologies and the architecture. We have chosen proven technologies for the most critical parts of our infrastructure. For instance we choose MySQL for our main storage, which is proven to work well for I/O bound workloads — that impacts the volume of data our tool is capable of handling — and has well-understood performance characteristics.

On the other hand, sometimes we needed to use more bleeding-edge technologies such as Golang. We like to use the right techno for the right task, and Golang is outstanding at writing highly concurrent code doing lots of I/O. Choosing bleeding-edge technologies is risky because you never known how it will evolve, or if it will still be alive in 2 years. For the anecdote: when we built Mention, AngularJS or React — today’s references — virtually didn’t exist. Therefore, we are using Backbone.js for our frontend: among all the libraries that existed at the time, it is basically the only one that remains alive.”

GNU/Linux Debian distro.

RAID everywhere. RAID1 for normal servers and RAID6 for backup.

MySQL, Kafka, Redis

PHP, Golang, Python, NodeJs

We are Monitoring them using StatsD, Graphite, Zabbix.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

Mention’s CTO journey to 400,000 users was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

…And then became Director of Mobile

Remember back in 2013, when reading files on “mobile” was new and everyone was wondering how the h*ck to do it? That’s when Martin Destagnol, entrepreneur and engineer, built Folders. And seven months laters, Folders got acquired by Aaron Levie’s Box.

Destagnol is now Director of Mobile and of Box Notes — the French “serial” “startuper” went from building a product in his apartment (we don’t get many garages in Paris) to managing a whole engineering team inside one of the fastest-growing startups in the Silicon Valley. How does one do that? Here’s the story.

Startup genesis and crazy-fast acquisition

As you might hear often times when wondering why an entrepreneur built a startup, Folders came from Martin’s own frustration: accessing cloud-stored files on mobile was just a pain. So he decided to build an iOS client providing the very best User Experience possible.

But Destagnol also brought a strong business rationale to the idea: as Folders was his 3rd startup, he knew what kind of risk he was willing to take and what outcome to expect. His previous company, Plyce, was a social network based on coupons, which had a great potential but also high risks. When coming up with Folders, his ambition was to build a product much more targeted, with higher chances of a “smaller scale” success. The bet was that one of the existing cloud providers could need a product like Folders; worst case scenario, he would still sell enough to make up for the money invested.

Then he shut down everything else but work, and built Folder in 7 months. Full time. Like, 24/7. As in 100% of the time.

Once the app was approved by the Apple store, Destagnol decided to come to San Francisco to show it to Box, Dropbox and Google Drive. The product wasn’t launched, but he figured the sooner he would show it to the big players to get their feedback, the better — for those of you who are reading from elsewhere than San Francisco, yes, that’s what happens here, you can just meet people like that. Hence Destagnol coming; although to be fair, he had some introductions.

Right after his first meetings with the platform and mobile teams at Box, they asked him if he could stay a little longer to show it to some additional people. They all clicked instantly, and at that point, Destagnol had figured out this meeting was actually going somewhere.

During the same day, Martin met with 13 different people including Aaron Levie, Box’s CEO, Sam Schillace, SVP of Engineering and Sam Ghods, CTO, who were freaking out over how great the features and UX of Folders were. When Box offered to acquire Folders, Martin knew instantly that it would actually happen: that’s “entrepreneur’s intuition”.

How can you make a cloud content reader app so cool, the CEO of “the” cloud content manager company thought it was impossible?

Today, Folders’ first features seem pretty obvious: fast picture loading, folder offline saving, snappy interface. But at the time, other products simply did not have them; in bigger companies, the back-and-forth movement between the product team and the engineering team takes a lot of time and energy. Product people make requests to the Tech team, the Tech team knows what’s possible or not, but does not necessarily have the overall vision. Destagnol had all the skills and was super detail-oriented; that’s how he managed to build the best UX, faster than them.

(tweet found, of course, via RudeBaguette)

Secret formula (don’t tell anyone)

[Personal Frustration + Business rationale] * hard work + entrepreneur intuition = Successful startup

How a hands-on builder becomes a manager at scale

When Destagnol joined Box, he started as a manager, and got carte blanche on re-building the whole iOS app for Box with a team of 10 people- and the opportunity to go up the ladder pretty fast.

Destagnol was basically coming to re-build everything using his ideas, which was potentially frustrating for the existing team. So Destagnol pushed the team to restart from a blank page together. They looked at each features and decided to take the best from both sides. That way, they all felt like they were part of a common project, and every engineer felt as if they were the owner of the decisions being made.

After a successful launch of the iOS app, Box asked Destagnol to do the same thing with Android as well. So when the annual review period arrived, Destagnol was pretty sure he would get promoted. After all, he had de-facto doubled the size of his team and had 2 successful launches. But he didn’t. And he was extremely disappointed about it.

When he discussed his non-promotion with Sam Schillace, SVP of Engineering at Box and former creator of Google Docs, Sam told him: “If we had promoted you, you would have become an assh*le” (he eventually became Destagnol’s mentor and they get along very well, in case you were worried).

“It may sound harsh, but this was the most valuable feedback I ever received, and it really transformed the way he was thinking about leadership” he says.

When you’re initially a hands-on manager, like Destagnol, it’s actually a huge challenge to learn to scale and delegate. What works when you are a small team doesn’t work anymore as you grow. He learned that it was not O.K to break an existing dynamics in a team, just to get results. Nor was it O.K to decide things by himself without bringing the team along with him. He had achieved outstanding results, but this had also led the product manager and designer to leave the company; so, even though the app launches went really well, there was an issue.

How to not be an assh*le and still be an effective manager, then?

For the next 6 months, after his reality check, Destagnol relied much more on his team to make decisions and was there only as a last resort. As a result, the team stepped up and felt more involved, and Destagnol got a lot more time to take on new initiatives. Destagnol started working with the Box Notes group and was promoted twice in a year. He now leads the iOS, Android, Windows and Box Notes teams, which represent more than 30 engineers and managers.

In a highly competitive atmosphere like the Valley, where every company is struggling to hire qualified people, it’s critical that Destagnol maintains a happy and productive team. For that, he makes sure to define a sense of purpose for each individual, which is a combination of many different things: how you believe in your company’s vision, how your own team contributes to it, what do you personally bring to it, how what you do is aligned with your career goals, how you get along with your teammates, etc.

All of these dimensions matter and every retention issue is related in a way or another to this sense of purpose. Destagnol and his managers make sure they talk openly and candidly with each teammate every week, so that can quickly identify issues and elaborate improvement plans with them.

“When questions are asked the right way, 90% of the action plan actually comes from the employee himself”, he says —” the extra 10% comes from the good manager”. In addition, Destagnol makes sure he is always reachable for anyone, especially as humility is a strong part of Box’s company culture.

Being a manager “at scale”, for Destagnol, means witnessing people growing around you. A manager’s own performance doesn’t matter, it’s his/her team’s that’s important. In a nutshell, Destagnol realized that a good manager makes himself optional.

Thanks Martin for this inspiring conversation. I hope this has encouraged you, other readers, to build your own. If’s it’s the case, see you back 7 months!

Interview + article by our Content Manager @VanierRachel

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

Did you like it? Hit “Recommend” and subscribe to our collection!

The story of the guy who sold his startup to Box in 7 months was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hi, I’m Guillaume, I am the CTO and co-founder of Wisembly, a SaaS solution facilitating interactions during your big meetings and events. We recently launched a beta of our new product: Solid to help you make your every-day-meetings more productive and actionable.

This is the story of how we improved our performance by changing and adding elements to our stack over the time. I’ll particularly focus on how using RabbitMQ on the backend to communicate between different stack and servers improved our life.

Where we once were

Here are the building blocks for our tech team’s philosophy: start small, DRY (Don’t Repeat Yourself) and YAGNI (You Ain’t Gonna Need It). Back in 2012, when we implemented real-time websockets communications with Node.js and Socket.io, we had a pretty small stack: everything fullstack on Symfony2 with MySQL as single storage and some tiny parts of Backbone.js here and there to power up our application. One year later I presented these slides at the Symfony2 Live Paris 2013 explaining how we implemented Elephant in raw PHP to communicate from our Symfony2 backend with our distant socket.io push server.

As I said, our stack was pretty minimal at the time. We didn’t feel the need to complexify it for the sake of the socket.io push server. So we looked at websockets and found a pretty way to implement them, connect and emit events with our Open Source library. It did the job, we open-sourced something cool (more than 500 stargazers now and still active!), on our way to live happily ever after :)… Or did we?

Where we are now

Quite recently, as the business was growing, more and more push events were sent every minute on the various customer meetings we handle daily. For example, we have a specific feature for very interactive seminars where more than 500 users can answer a live poll. Oftentimes, all the attendees submit their answers during the same 10-to-20-second time window, right after the poll is launched by the presenter. Aside from some MySQL resource concurrency problems (deadlocks) we had to deal with our friend Redis (that’s another story we might tell another time). We also had to deal with server pressure, as you can guess.

We had pretty shitty response time from our API. Skyrocketing from an average of 125 ms to ~350 ms, some time even more! The process was putting much pressure on php-fpm worker that had to fork again and again, spawning many children to the configured limit to handle all the sudden workload. It jeopardized other clients who were using the solution at the same time.

We ran blackfire.io and look deeper into New Relic data to spot bottlenecks, and then looked at our code to find where we could improve performances. We quickly noticed that external calls to the push server through cURL with Elephant were quite time and process consuming!

Sh*t! Suddenly we realized that we could improve code here and there, add cache or move things to Redis to reduce concurrency and improve throughput, but the push events communication layer with our beloved and loyal Elephant would still be a burden!

Looking at our stack

When we stumbled upon this problem, we then looked at our ways to overcome that by taking a closer look at our stack. Since 2012, we’ve had two powerful allies: Redis and RabbitMQ. Both of them are great to publish events with data and a great way to communicate between servers.

We finally chose Rabbit as we were already using it intensively with Symfony recently and the great Swarrot library. In a few minutes, thanks to amqplib and 50ish new lines later in our node pusher app, we connected our node server to our Rabbit queue and added the ability to receive events through websockets AND Rabbit.

In one more hour, we created a RabbitTransport with the exact same interface as our ElephantTransport. A simple Symfony config parameter later, the push events emitted by our API were not sent through Elephant but put in a Rabbit queue instead. And like magic, there were rightfully consumed by the distant push server, and it was blazing fast.

Performance improvements

Alright, after 3 long years of faithful and loyal service, could we get rid of Elephant, our baby, in only 3 short hours? Let’s dive into the numbers.

Fist of all, A to Z process (time between API call and broadcasted event reception) was not affected, even slightly improved: push events are received in less than 90ms (they still are received by listening users before the user that made the action receive the API response!). This does not vary a bit, even with 1000 events fired in a second to a single user. Good.

Then, looking only at server side, let’s try to send 100 “consequent” push events to our push server. On a standard developpement machine (1,8 GHz i7 dual core, 4GB Ram):

• SocketTransport (with Elephant): 100 events took 8936ms
• AmqpTransport (with RabbitMQ): 100 events took 521ms

No typo here, you read right: about 17 times faster! We did not bother measuring the CPU consumption for that, as these results were more than enough.

Quite frankly, we supposed that PHP curl implementation that powers the core websocket communications of Elephant was more greedy than lower level RabbitMQ implementation (we use the pecl C implementation for Rabbit in production that even speeds things up a bit), but to that extent…

Last thing to check: the push server’s ability to consume events stored in a single queue as fast as they come in. For now and unless we deal rooms with more with 600 users, it appears that node/amqplib/socket unstack events from the queue like a charm. Once we’ll reach a limit, we’ll think about adding more push consumers to keep the pace going.

API mean response time < 100 ms after deploy, external calls (in green) reduced

Where we’re heading

This story showed us that living without Rabbit and using Elephant to keep the stack simple at the time we were 2–3 devs was acceptable and allowed us to scale our application and business in a simple way. As usage grews, the need to refactorize parts of our application as codebase gets old and stack improves are needed. But it was all possible thanks to the awesome work we did in the last months on Rabbit.

Speaking of it, we now also use it to power other parts of our application. We use Rabbit to speak with various APIs, to make things asynchronous (emails, exports, stats, document conversion, heavy jobs). For example in Solid we are able to give you stats and insights about how long you spend each year in meetings by asynchronously crunching Google or Office365 calendar APIs and push you the result once it is done.

Two years ago, we were fine living without Rabbit. Today, we couldn’t do without it.

If you’d like to see it in action, you can signup for Solid here!

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

How we scaled Wisembly’s infrastructure : moving from our Elephant to RabbitMQ was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

In the past 5 years, I have been Chief Technical Officer of two startups — one, GoCar has been acquired and one, Solved, has been discontinued — and helped many others as a technical advisor. What characterizes startups is that they have to ship a lot of results with limited resources. As CTO, your daily job is to lead the technical team, set the goals and take the right technical decisions. You are in a constant tradeoff of immediate speed VS long-term productivity.

In this article, I want to share 5 rules I follow in order to make my choices. So far, they enabled me to keep shipping while avoiding to pile up “technical debt”.

1. Dedicate yourself to the business

The goal of any startup is to build a solution which will bring value to its customers. There are chances that your business co-founder will spend most of his/her time talking to them and understanding their needs. On this basis, your co-founder will set the priorities and report what customers’ problems are. Your role will be to find out and build an outstanding product that provides a solution to them.

As a technical person, it is easy to get excited by a new technological challenge or a new service that looks promising. When it occurs to me, I ask myself this simple question: “What is the business outcome of what I am doing”. This way, I always know if I am working on the right priority or not.

At Solved, we even dedicated a weekly meeting with my business co-founder, Thomas, where we were reviewing the features to ensure they match the business priorities. At any moment, I and any member of my dev team could say why we were working on any feature.

In order to ensure I did a good job, I was asking myself: how will it delight our users? how will it help our startup to make money? or help our operations team? If you can also answer these questions for your own project, there are chances you are on the right track.

2. Optimize for speed and flexibility

In its early days, your startup’s main challenge is to find the product-market fit. That means that your product embryo might evolve in many different directions and it has to evolve fast. As you don’t know how long it will take to get traction, you have to balance short-term benefits as well as productivity in the long run.

At the code level, I found out that the best way to do that is to organize my code in small, reusable modules that I can assemble like Lego bricks. It enables to quickly change the business logic and the flows of the app. In order to maintain a clean codebase, I never hesitate to throw away features that are not needed anymore.

As an illustration, here our Trello Board at Solved, my previous startup:

At the organization level, I put in place simple processes so that everybody knows what are the priorities and who is working on what. Most of the time a simple Trello board with the main tasks will be enough. I make sure not to go into too much detail in order to leave room for discussion. Often times, the best ideas and the tiny details that make the difference will come from these discussions.

3. Choose the right tool for the right job

There has never been so many tools in a developer’s toolbox. You can choose to externalize most of your dev stacks or to develop every single tool yourself.

At the beginning of your project, one of your main challenges will be to choose your stack. New tools and technologies have probably emerged since your last project. Should you choose a stack you already know or try a new one?

I never underestimate this phase since it will influence the whole life of my startup. I’ve seen too many CTOs struggling because they chose the most “trending” tools without realizing what are the technical implications. It is not because everybody is using a tool that this tool will fit to one’s particular case. For every tool I consider, I do my best to understand what are the pros and the cons. If I only see pros, it is often a sign that I have not dug enough.

For instance, I hear many developers thrilled by the power of MongoDB. So much that they use it in all their projects without realizing that it lacks of some SQL DB features they might need (think of the work required to maintain many-to-many relationships in Mongo). After a year spent coding, they are not taking advantages of Mongo and start struggling because they do not find the features required by their project. If they had taken the time to understand the pros and cons of each solution, they would have chosen the right DBMS from day one.

In order to make the right choices, I take time to understand what are the specificities of my project and what tool will answer the best to these ones. I especially like to discuss with other people who have tried these tools.

4. Hire people who are more skilled than you

When it comes to hiring, you might be tempted to start with interns or junior developers since they are easier to recruit and are more affordable than senior programmers. However, with inexperienced recruits, you will end up spending more time training them than actually shipping code. Never forget your goal: being fast and flexible.

I have experienced that hiring senior developers bring way more value to startups. Since I do not have to train them, I have more time for my own responsibilities. Moreover, they bring their own knowledge, their own tools and can help the team to take better decisions.

I even try to hire developers that are better than me in domains I consider key for the startup. Since I do not know everything on every subject, I am delighted to delegate responsibilities to members of my team. However, I ensure to understand what they are doing so that I still have the big picture and can coordinate the team.

At my previous startup, I had shortlisted two candidates who fitted to the team I wanted to create: one junior and a more senior (read 1 year vs 5 years experience). Choosing Sandro, the more experienced of the two, brought our startup much more than I could have expected. In addition to its experience, he brought his maturity and his culture of effectiveness that he had acquired during his career.

5. You are the example

Never forget that the whole team is looking at you. You set the standards and best practices. Whatever you do or don’t do, your teammates will follow you.

In order to ensure everybody speaks the same voice, I set up code policies and style guides at the very beginning of the project. I strongly believe in peer code reviews. It has been proven that they help communication in company, ensure a better code quality and reduce the number of bugs. At my previous startup, the policy was “two set of eyes on every line of code”. Every commit I wrote was reviewed by Sandro and vice-versa. Instead of committing directly to master, we were doing pull requests on Github that we merged once everything was ok.

Here is an example of a typical pull-request at Solved:

Finally, I’ve found very important to do things before delegating them. If I do not know what I am asking to my teammates, it is very difficult to discuss their choices and put the reflexion further. Even if I do not do the things as well as they would (that’s why I hired them), doing it by myself in the first place give me fine grasp of the challenges they are tackling.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

5 things I’ve learned being a CTO in startups was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

Last week, Point Nine Capital invited the CTOs and VPs of Engineering of their portfolio companies. The event took place in Google’s offices in Berlin. I was flattered to get invited and had the opportunity of spending the day next to great people from famous startups such as Morten Primdahl, Co-founder and CTO at Zendesk, Spyros Magiatis, Founder and CTO at Workable, or Johannes Ziemke, Platform Engineer at Docker.

Nicolas Wittenborn on Twitter

Lots of brainpower in the room at the #p9techcircle thx to @GoogleDE for the great location! pic.twitter.com/yGTZJsxgL2

The agenda was quite packed with interesting topics around scaling tech and teams. You can find the complete agenda on this post written by Rodrigo Martinez, who did a fantastic job organising the event.

Next to great tech-centric talks (e.g. Continuous Integration Best Practices by Florian Motlick, CTO at Codeship, Microservices by Andy Smith, CTO at Werker etc.), an important subject was hiring and scaling teams. In other words: a mix of the most important topics you need to know once you have traction. And as the CTO of one of eFounders’ under-development startups, this really struck a chord.

So here are my key takeaways from this meetup.

Takeaway #1: The hardest problems when scaling up are most of the time non-tech problems

The panel was called ‘Best Practices on Scaling Tech’, but after a couple of minutes of discussion, it became very clear that the bottleneck is mostly due to organizational challenges.

Indeed, answers to well known technical problems such as how to scale a MySQL database are available most of the time. Despite all your preparation, be ready for your 3am emergency alert, stay focus, and you’ll resolve the problem. No, your true challenges will come from human and managerial situations.

Your job as a CTO is to have a working team in place which can perform, produce and scale with the success of the startup. Hiring tech talent is increasingly difficult and even if you manage to hire, scaling a team is not trivial. You need to find the right team size and get organized in a scalable way. The success of your startup heavily relies on how good you are at that (read the original article).

The success of your startup depends on your ability to scale your tech and tech team.

Takeaway #2: Try to maintain a pipeline of talents

According to Ivo Betke’s Keynote, every startup should have a talent pipeline. According to the Webcrowd.net founder:

“The average time a developer stays in a startup is down to 1.4 years in Silicon Valley and around 2 years in Berlin. It’s crucial to maintain a big network of talents.”

That being said, it’s not as simple as it sounds, and you’ll probably find yourself one day at a point where you need to rely on external recruiters if you want to hire fast.

In any case — internal or external talents — you still need to follow some rules and techniques if your want to hire the best (and you sure do).

Move very fast at the beginning of the process

A developer gets easily hired within one week. If you don’t quickly make a decision, you might just miss out an opportunity.

Filter your pipeline

Instead of spending 2 hours on-premise for each candidate, start with a short Skype interview. This will allow you to talk to a lot more candidates, and filter out the ones which don’t fit the open position before engaging further with the recruiting process.

Always make a good impression, even if you do not hire the candidate

While this should be obvious, a lot of startups make this mistake: once they decided to not take a candidate, they forget to end the hiring process properly. Don’t forget that a candidate still has a network you could tap in.

Stay in touch with candidates

Follow up a couple of months after talking with a candidate. As the average time spent in a startup is quite low, you might get lucky and catch someone who actually wants to leave his current position.

Lower the requirements on your ad

Too many job descriptions just look like a Christmas list. Don’t put all the requirements you can think of on your advert. You might miss out on great talents by doing so, who could easily learn the missing requirements. Just keep the ones that are crucial for your company, and discuss the other ones during the Skype interview.

Ivo Betke’s recipe to recruiting the best talents:

Maintain a pipeline of talents, and polish your recruitment process to make a good impression and hire the best

Takeaway #3: Promote internally when it makes sense, Hire from the outside when you need to go fast

After Ivo’s Keynote and a presentation from former CTO of Brands4Friends Stephan Schmidt on building high-performance tech teams, the next panel tackled the actual scaling up of tech teams.

To scale up your tech team, do you promote internally or recruit externally?

My biggest wonder was concerning people development, e.g. promoting a developer to a management position. I asked if people had success stories to share on the topic.

The answers to this question were quite diverse and it seems to depend heavily on the situation.

One good example was given by Wiktor Schmidt, CEO of Netguru, who scaled his team from 50 to 100 developers within one year. In his case, a lot of key positions are handled by early employees who grew their responsibilities together with the startup.

Another interesting thought from the panel was on considering each individual case. It is wrong to assume that all developers aim at becoming a manager at one point in their career. Actually, it’s quite the opposite: a lot of developers don’t want to manage people and aim at becoming excellent senior engineers. If that’s the case, pushing them into a management position will just make them unhappy and probably drive them away. So make sure you discuss it thoroughly before making any move.

In any case, it became clear that once you have real traction you need to grow your team really quickly. So filling up key position with external candidates might become the only realistic option.

Between internal promotions and external recruitments, make sure you choose wisely and bear in mind individual aspirations.

As I mentioned earlier, the day was packed with interesting Keynotes and one could easily fill several blog posts with all the takeaways. I really enjoyed the fact that keynotes and panels where around “soft” topics like hiring and team scaling.

As written in Rodrigo’s post, this kind of knowledge is not available on the usual tech platforms like StackOverflow, Quora and so on. It’s something that you build with experience — or that you want to hear directly from someone who experienced it. Having the possibility to follow up with questions was amazingly valuable to me. Definitely an event I would love to attend again if I get a chance. Thanks again Point Nine, you nailed it!

Are you a programmer? Read those tips to be hired by a great tech startup.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

3 Takeaways from Point Nine’s CTO Event on Scaling Up Tech and Tech Teams was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

I have been working on Meteor projects for more than 2 years now. I already shared the reasons of this choice in a previous post. Today I want to address the question of file structure.

Unlike frameworks such as Ruby on Rails, which has clear instructions on how files should be organized, Meteor lets you decide how you want to structure them. It only sets a handful of rules on files priorities.

For instance, files inside a directory called lib are always added above all other files. Also, Meteor sorts all files in alphabetic order.

But this autonomy leaves first-time users with a lot of questions, as you can see on StackOverflow

or on Meteor’s forum.

Obviously, the topic is hot.

Abigail Watson, a well-known developer in the Meteor family, wrote an article about it. In her awesome Meteor cookbook, she dedicated a section to describe the different file structures, depending on your project. As you can see, there’s more than one solution.

So, how do you set up the right structure for your project? Here are my thoughts and return on experience based on the different projects I run at eFounders.

Why I decided not to follow the Ruby on Rails file structure

Meteor evangelist Josh Owens (if you don’t know him, he’s the guy behind Meteor news site crater.io, The Meteor podcast, and The Meteor club) reuses part of the directory structure used in Ruby on Rails. But as he explained in this article, his main reason for doing so being “having spent 9+ years working with that framework”, it didn’t convince me (no offense Josh).

Going a step further, here are my reasons not to use the Ruby on Rails file structures.

First, it generates too many small files and directories. You end up with tenths of open tabs, and switching between tabs can very quickly become annoying.

Second, I almost always work on a specific task on a specific part of the app (let say the comment system of a blog). Therefore, I like to have all files related to this task close to each other so that I can easily find and edit them. And the Ruby on Rails structure doesn’t let me do that.

For instance, let’s take a blog. Imagine you have a commenting module and you want to display the date on which each comment was posted. To do so, you have to update 3 different files:

• add the date on the comments collection — client and server
• update the template related to the comment to display the date — client side
• update the method to insert the date on which a new comment is posted — server side

In a typical Ruby on Rails structure, you will have to dig through 3 different paths spread across the project to find those 3 files. I prefer opting for the easy way.

Let me share with you 3 optimal structures on Meteor.

Three file structures I use and recommend, based on the size of your project

Flat organization

For a small project, Meteor lets you use a pretty simple file structure. When you create a new empty project, it will generate:

• one single .js file with your entire code (client and server)
• one .html with all html
• one .css with all the styles

Here’s how it looks:

While it’s often enough when you create simple packages, I strongly recommend splitting files in a more structured way for more complex projects.

Package Oriented

For big or open source projects such as Telescope, the ultimate solution is to use packages to split functionalities. This method gives you the flexibility to decide to use some features or not and to manage dependencies between packages.

As Meteor says in its documentation:

This is the ultimate in code separation, modularity, and reusability. If you put the code for each feature in a separate package, the code for one feature won’t be able to access the code for the other feature except through exports, making every dependency explicit. This also allows for the easiest independent testing of features. You can also publish the packages and use them in multiple apps with meteor add.

Indeed, it is the ultimate solution, but it also takes more a time to create, update and manage those packages. For instance, each time you want to add a file, you will need to update package.js to include this new file. Same goes for file editing, removing, etc.

As you can see, maintenance can be pretty heavy and time-consuming. Therefore, for my latest big project for eFounders, I implemented an intermediary approach, splitting files by features or module.

Module Oriented

Keeping the same example as above, all files linked to the ‘comments’ module of my blog will be stored close to each other. You can find them and access to the code in a heartbeat, as in the ‘package oriented’ approach.

However, this method gets rid of the package.js file, thus it becomes as simple as the “flat organization” of files as described above.

Here is how it looks like:

As you can see, all files related to the module banq are now together. Each file contains the code for a specific Meteor system, one for events, one for helpers, one for collection, one for publish, ...

A “module oriented” file structure balances easy maintenance and file separation.

I’d love to know how other Meteor users structure their files: feel free to share it in the comment section.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

Did you like it? Hit “Recommend” and subscribe to our collection!

How to organize your files on your Meteor projects was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

A risk management perspective

Yann Lechelle (LinkedIn, Twitter) is a Paris-based entrepreneur with a number of pivots under his belt. He was founder and CEO at Etheryl (acquired by private investors), co-founder at KickYourApp.com (acquired by Change), co-founder and COO/CTO at Appsfire.com (acquired by MNG), co-founder at Sonetin.com and currently COO at Snips.ai using AI to make technology disappear. Yann occasionally invests in and advises other startups, on pivots among other things!

~

TL;DR: this post discusses the generic notion of a startup pivot. Technically minded readers might prefer to focus on the product & tech sections, or anything else in bold.

Pivots are a fact of life in the startup world. Yet, very few founders, especially first-time founders, will provision for it. The founder mindset is typically focused on a single go-to-market strategy. The investors are sold on the potential based on that initial strategy, signing off a budget calibrated accordingly. Everyone sings the same tune until the shareholders realize, hopefully before it’s too late, that the strategy is going nowhere, and that a radical change is required. This scenario occurs more often than not, over 65% of the time according to Fred Wilson.

While this iterative process appears natural, and with the benefit of hindsight, accepted and even praised as part of the startup folklore, it remains a traumatic event from the inside, and possibly a direct cause for failure. Reversely, if done right, a pivot is almost inevitably cause for success.

Structurally, there can only be a handful of pivots within the lifetime of a company. Repeat entrepreneurs may have experienced it multiple times and therefore developed their art of the pivot… hence becoming pivot artists, a trait that VCs should consider as key risk management expertise! Here are a few awesome pivot artists:

• Multi-pivot repeat entrepreneur Stewart Butterfield: from video game to Flickr and from video game to Slack; product & vision pivot.
• One-time-pivot entrepreneur extraordinaire Mark Zuckerberg: from Hot or Not to The Facebook; product pivot, vision developed in hindsight?
• Multi-pivot co-founders Jean-Baptiste Rudelle, Romain Niccolini and Franck Le Ouay: CRITEO and its 3 pivots to become a (too rare) French Unicorn.

Let’s go back to our humble startups and itemize some of the issues that may arise during a pivot (with first hand examples):

• A sudden shift in business model affects the former revenue stream and structure, therefore affecting the operating budget;

For example, killing a revenue generating B2C product will certainly reduce the top line and increase the monthly burn. The lifeline suddenly becomes shorter.

• The team that had grown according to the needs of the previous product suddenly needs to be recast to the new configuration, leading to casting and head-count mismatch;

For example, a team that had built an architecture around complex and intertwined relational databases with a balanced mix of read/writes suddenly needs to reconfigure for a product that needs massive reads (100x) optimised for low latency with a noSQL-based and map-reduced architecture. Different skills, different architecture, new learning curve.

• Parts of the older product needs to be transitioned, phased out, or worse maintained to some degree;

For example, when the pivot requires to move from B2C to B2B, when do you pull the plug on the B2C product? Does it affect your revenue? It is probably a good idea to give reasonable notice to those users who have embraced your initial product; it is essential that those very users are onboard with the pivot and keep them as potential ambassadors of your brand equity. Who on the team can help maintain the legacy solution? for how long? should they instead focus on the new product?

• A new product needs to be developed, hopefully by leveraging existing infrastructure, skills, and capital, all of which are now more constrained;

For example, shifting the model from B2C to B2B may involve refactoring a single platform into a SaaS offering… resulting in multiple instances of the same product. Other examples may involve refactoring some of the code and accelerate the design of a brand new product, for example by going up or down the value chain), while at the same time keeping the same clients or partners to speed up the go-to-market this second time around.

• Worse of all, the time and energy considerations are now more constrained than ever: this is possibly the most difficult aspect to manage.

Here the founders need to lead by example, be on the ground and with the team at the same time; in a way, back to square one.

As you can see, most of the above issues are product related, and yet fundamentally anchored in the HR ability to turn things around. Indeed, entrepreneurs thrive on constraints, and a pivot may in fact correspond to “a second wind”.

How does one prepare for a pivot, or rather, how does one create the proper conditions to pivot properly?

Let’s break it down around three main pillars: product & tech, HR, and capital.

Product & Tech Challenge

The product initially defined by the founders typically emanates from a global vision. In some cases, founders will start with the product and later realize, on their own or with external help, that there is a greater vision. Either way, the team must strive to work towards the greater vision, and consider that the product itself is just a means for achieving a greater goal. This serves two distinct purposes: pitch investors at a higher level of ambition (helps with the valuation), but most importantly, helps the product and engineering team build a category of assets that will be reusable when pivoting the product within the general framework of their vision.

For example, building an architecture that isolates fundamental blocks of logic and imposes inter-process communication by way of a proper API supporting OAuth 2.0 may help migrate from a B2C product to a B2B offering that exposes those APIs to external entities. Building a B2C product that way may require a little more time and effort, but is in fact the correct way. Shortcuts or sloppy execution can easily turn into technical debt which is extremely penalizing in case of a pivot.

While the pivot is a general management directive, the CTO is a key decision maker in this process. Indeed, only the CTO has a global view on the existing architecture and the individual skills that the technical team possesses. Reversely, smaller technical teams may be better at instigating what the new product could be. Either way, at the board level, the CTO can steer the ship smoothly towards a new product that leverages the current skillset and architecture, or else agree to ignore those assets and embark on a radically new creation (at a cost).

It helps if the vision is both ambitious and not dependent on exogenous platforms like Facebook, Twitter, Apple or Google. With Appsfire, a company that I co-founded in 2010, our vision and mission was to solve “app discovery”. Unfortunately, that vision had very strong dependencies with the App Stores. Towards the end of 2013, changes within the App Store guidelines made our model unsustainable… forcing us to pivot both at the vision and product levels; a much harder feat.

Reshuffling the business model, or reshuffling a number of technical assets to re-define the product is much easier than having to start from scratch, in addition to helping keep the momentum and timing to achieve the holy grail: the product-market fit.

HR

It’s the people, stupid! It always boils down to the people doesn’t it? Indeed, a startup isn’t a financial play on its own. It may be at the VC portfolio level, but at the micro level, within the startup itself, it’s all about energy and productivity, about beating the odds and overachieving, it’s about the core vision and the ability for the founders and the rest of the team to bind to it.

To that effect, to ensure that the team is effectively able to pivot, it should be composed of two key groups:

• the hard core team: founders and first employees. They must demonstrate charisma and the stamina to go the extra mile, especially during hard times and periods of doubt. They will lead by example and explain why the pivot is necessary, in full transparency.
• a larger group made of polyvalent engineers (also known as the talent): full stack, avid learners, passionate bunch, agile minds, sprinters (and not just in the agile sense), team players… typically people who are not too affected when their project suddenly shifts gears and they have to step outside of their comfort zone or preferred coding language or IDE.

A third group inevitably exists and is made of people who are either back-office (accounting, finance), sales and business development agents, or technical specialists. During a pivot, some of these people will see their workload dwindle rapidly: if the business model changes, there is perhaps suddenly no more invoices to produce, nothing to sell for a while, or at the technical no need for a specific expertise that made sense pre-pivot. In the US, it’s quite easy to thank people and let them go — a harsh reality and necessity. In France, the labor framework does not make it easy even though, contrary to popular belief, it is definitely possible and reasonable if done right. I would argue that if the reason is communicated properly, employees will understand that the pivot creates a “casting mismatch” and that they are often better off by leaving the company. Working with them on their transition to a new job, or mutually agreeing on a smooth “exit” will give them ample time to rebound at a reasonable cost to the startup (the rest will be covered by the government’s unemployment subsidies).

Capital

At the capitalistic level, the pivot brings an interesting paradoxical twist. While the team and founders may have found a way to better address the market, they will almost inevitably do so from the existing cap table, and without fresh capital. Pivoting means the board acknowledges a local failure, and yet, the action of pivoting, in fact allows a swift and more educated go-to-market approach, bearing less risk, and therefore value creating.

It could be argued that if the pivot is radical enough, then the team and founders should probably start from a clean slate: new company, fresh cap table, and funds dedicated to the new product. Call it emotional attachment, loyalty or ignoring the notion of sunk cost, founders will often honor continuity and momentum even if it means less than ideal capitalistic terms. VCs should probably acknowledge that and recognize that a pivot done right deserves a little readjustment or nudge towards the effort. Reversely, when comes the time to pivot, founders should perhaps approach their investors in earnest and plead towards a new set of terms and incentive: relution against cash if pivot succeeds, dilution otherwise.

In reality, entrepreneurs keep at it and pivot within the capitalistic framework inherited from the pre-pivot period. To that effect, I only have one piece of advice: raise more funds if you can by adding some padding to your budget. In short, within your fundraising round, provision for a pivot by allocating an extra 50% of your initial budget. Early stage investors (seed or series A) will be more interested to discuss this notion of padding for a potential pivot rather than discuss unrealistic 3 year projections.

To conclude…

Pivoting is in fact a corollary to the fail fast doctrine. Execution and focus are key ingredients to a successful path until you reach that dead end. Yet, nothing prevents startup founders to think in broader terms, provision for the (almost) inevitable pivot by creating financial padding, recruit polyvalent talent, and finally productize around the vision rather than digging a grave around a mono-product approach.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

You like? Hit “Recommend” and subscribe to our collection!

The art of the startup pivot from a founder-CTO point of view was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

Roy Fielding’s dissertation thesis on “Architectural Styles and the Design of Network-based Software Architectures” albeit published in 2000, is still a goldmine in 2015. For those who are not familiar with Fielding’s work, he is one of the authors of the Apache web server, he has worked on the first specification of HTTP, and he is the father of the REST acronym.

A REST architecture is an architecture that MUST (as in RFC 2119) respect the following architectural constraints:

• client-server
• stateless
• cacheable
• layered-system
• uniform interface
• code-on-demand (optionally)

HTTP and the 2000’s World Wide Web, fit perfectly in this description of a REST architecture (in fact, REST constraints seem to be chosen so that systems that would respect these constraints will look like the web ☺)

15 years later, everybody builds RESTful APIs. These APIs take full benefit from HTTP (and thus, from its REST-base architecture) but most APIs do not fully respect the “uniform interface” constraint.

In the Fielding sense, an API is really RESTful if it respects the uniform interface constraints:

• resources are unambiguously requested via URIs,
• representations of resources are manipulated (you’re always playing with a “view” of a resource, not the resource itself),
• messages are self-descriptive and self-contained,
• transitions and actions should be clearly exposed to the client by the server, via hyperlinks and hypertext. This point is often referred as HATEOS: Hypermedia as the engine of application state.

A classical website, like the one from which you’re reading this article, uses hypermedia as the engine of application state. You’re viewing representations of resources and, on each of them, a set of actions (going back to home, viewing a related article) is actionable via hypertext links. Clicking on one of these links will (hopefully) give you another view of another resource, modifying the application state.

Those links are materialized and explained by meaningful text and iconography to help you do what you want to achieve. The web everybody knows is fully compliant with the HATEOS constraint.

HATEOS constraints applied to APIs

Fine, but what’s the point with APIs? Let’s take an example with a widely-used API; the Twitter one. Twitter API exposes a way to retrieve your friends by doing the following call over HTTP

GET https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000

Then, the reply (as documented here) will be something like:

{
  "previous_cursor": 0,
  "ids": [
    657693,
    ...,
    783214
  ],
  "previous_cursor_str": "0",
  "next_cursor": 0,
  "next_cursor_str": "0"
}

Without any knowledge of the twitter API structure, what actions are easily actionable from this response? NONE.

Server developers are responsible for providing the next actions a client can take from each point in the application.

This is exactly where HATEOAS comes into play.

By being non-HATEOS compliant, most APIs, including “big” ones, do not respect the uniform interface constraint as defined by Fielding. Does it means that the web (well, APIs) is broken? NO ☺

Now, two hard questions arise:

• “As a client developer, is it really possible to create an API client smart enough to use hypermedia relations to perform actions on websites without any knowledge of the website structure?”
• “As a server developer, can I describe my application logic via links and relations that would be self-comprehensive by any hypermedia client?”

For instance, if every social network would expose Hypermedia APIs, fetching my friends on each of the network would be as easy as:

client(any_website).auth(login, password).get_friends()

(here: our client would request the “/” of the social network api, get the Content-Type to parse the response, look at any available link relation to authenticate, and then look at any available link relation to retrieve friends.)

The (optimistic) answer for these two questions is YES. Hypermedia advocates put a lot of energy in standardizing the web to allow the emergence of Hypermedia APIs:

• by creating formats for our APIs: Atom+Pub, Collections+JSON, Siren, HAL, …
• by creating repositories of link relations (see schema.org)

To approach hypermedia APIs, it is important to understand that every media type (or Content-Type) should define a processing model.

Said otherwise, keep in mind this question: “What would a browser do with my response?”.

Hypermedia APIs remain not massively used

Sadly, there are a few limitations that could explain why Hypermedia APIs are not widespread:

• writing an exhaustive list of link relations seems unrealistic: even if efforts are made to simplify the description of new link relations (JSON-LD is a good example)
• APIs are not (quite) the web, they are designed to interconnect services and feed end-user applications. Using hyperlinks and describing link relations yield bigger (in size) replies and slightly more requests in a world when connectivity is still an issue in many cases (notably in mobility: smartphones, etc..)

Another reason for the rarity of such APIs might be the lack of commitment from WEB giants. Google might be the only one (as far as I know) to provide a Hypermedia API (their XML responses respect the AtomPUB format).

But there are a lot of things to learn and some benefits to take from Hypermedia-based APIs:

• definition of a processing model according to a Content-Type (or simpler: formatting of replies),
• comprehensive description of your API via links and their associated descriptors (especially standard ones as defined by the IANA).

Hypermedia API case in point

Let’s now go back to our previous example. As already described,

GET https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000

would return the following response:

{
  "previous_cursor": 0,
  "ids": [
    657693,
    ...,
    783214
  ],
  "previous_cursor_str": "0",
  "next_cursor": 0,
  "next_cursor_str": "0"
}

Under a “hypermedia” light, this response has several limitations:

• I have a list of id, which are, as we can guess, our friends’ ids, but what can I do with these? How can I fetch their user information?
• As a human, I guess that next_cursor is something to fetch the next page of ids, but what is the associated URL? And is there something more generic to say that something can be used to fetch the previous and next page of results?

In fact this answer is full of conventions. These conventions are documented in a human-readable format and accessible via twitter’s developer website.

Hence these conventions should be coded by a human within a library, leading to a strong coupling between client and servers.

The lack of URL usage in answers leads to a high number of links hardcoded in client APIs.

As an example, here is the output of a search for “url” in a python twitter api client.

Let’s try to make this answer a bit more « Hypermedia ».

IANA standard relations type (http://www.iana.org/assignments/link-relations/link-relations.xhtml) defines « prev » (or « previous ») and « next » relations as:

• « prev »: indicates that the link’s context is a part of a series, and that the previous in the series is the link target.
• « next »: indicates that the link’s context is a part of a series, and that the next in the series is the link target.

Our previous answer could be rewritten as:

{
  "prev": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000",
  "ids": [
    657693,
    ...,
    783214,
  ],
  "next": "https://api.twitter.com/1.1/friends/ids.json?screen_name=twitterapi&count=10&cursor=0",
}

Then for each id, you could decide to return a data structure that could give you useful information about the user: lookup (as described in twitter api), friends, timeline, etc… It could give the following rewrite of your answer:

{
  "prev": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000",
  "ids": [
    {
      "657693": {
        "user_lookup": "https://api.twitter.com/1.1/users/lookup.json?user_id=657693",
        "friends": "https://api.twitter.com/1.1/friends/ids.json?user_id=657693"
      },
      ...,
      "783214": {
        "user_lookup": "https://api.twitter.com/1.1/users/lookup.json?user_id=783214",
        "friends": "https://api.twitter.com/1.1/friends/ids.json?user_id=783214"
       }
    }
  ],
  "next": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=10&cursor=0",
}

But wait! Here “user_lookup” and “friends” are not described as standard relations links in the previous IANA link relation lists. That is true, and it is, as described earlier, one of the fallacies of hypermedia. Here, the fun fact is that even the Person « type » described by schema.org does not expose a « friends » link relation.

Finally, this response does not fit any existing format. With collection+JSON, the previous response might be:

{
  "collection": {
    "version": "1.0",
    "href": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000",
    "links": [
      {
        "rel": "prev",
        "href": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=5000"
      },
      {
        "rel": "next",
        "href": "https://api.twitter.com/1.1/friends/ids.json?cursor=-1&screen_name=twitterapi&count=10&cursor=0"
      }
    ],
    "items": [
      {
        "href": "https://api.twitter.com/1.1/users/lookup.json?user_id=657693",
        "data": [
          {
            "name": "user_id",
            "value": "657693"
          }
        ],
        "links": [
          {
            "rel": "user_lookup",
            "href": "https://api.twitter.com/1.1/users/lookup.json?user_id=657693",
            "prompt": "User Info"
          },
          {
            "rel": "friends",
            "href": "https://api.twitter.com/1.1/friends/ids.json?user_id=657693",
            "prompt": "Friends",
            "render": "collection"
          }
        ]
      },
      {
        "href": "https://api.twitter.com/1.1/users/lookup.json?user_id=783214",
        "data": [
          {
            "name": "user_id",
            "value": "783214"
          }
        ],
        "links": [
          {
            "rel": "user_lookup",
            "href": "https://api.twitter.com/1.1/users/lookup.json?user_id=783214",
            "prompt": "User Info"
          },
          {
            "rel": "friends",
            "href": "https://api.twitter.com/1.1/friends/ids.json?user_id=783214",
            "prompt": "Friends",
          }
        ]
      }
    ]
  }
}

(note: As mentioned earlier, this response is far bigger compared to the original one, this is a huge limitation of hypermedia responses)

To conclude, why would we consider this rewrite of a Twitter response as better?

I think that every API should have the following qualities:

• stable
• comprehensive
• adaptable

Providing links in your replies will let you change the link destination of a resource, making your API adaptable, and somehow stable (if client developers do not make any assumptions about your URLs)

Providing relations will make your links comprehensive and will make your responses self-descriptive.

Using a stable format will make the format of your replies predictable and, as a server developer, will give you a guide to forge responses.

Following this advice might let you build APIs that would be more adaptable and their clients might be more resilient to changes.

Useful Resources

If all of this makes sense to you, I truly recommend you read this book. Mike Amundsen is one of the best advocates of Hypermedia APIs and this book goes deep into standards description.

I should mention too traverson which is the coolest attempt to build a functional hypermedia client and HAL browser which is a project where you can play with HAL. By the way, you will find a short API client for HAL browser in one of my slide deck here.

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

You like? Hit “Recommend” and subscribe to our collection!

How your API could benefit from Hypermedia was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.

Hi there. My name is Nicolas Mondollot, I am the CTO of Drivy — an awesome peer-to-peer car rental service. We launched our german website in early 2015. Here are some things we learned along the way.

When you start a website you usually start small: one website, hosted on one domain, targeting one country and one language. Simple, right?

Then, one day you decide to go international (exciting!). One problem, though: people don’t all speak/read the same language everywhere. You must localize you content in multiple languages.

The standardized way to do so is to use a locale for each language and geographical region you are targeting. For instance if you want to make your website available in the US, France and Canada you’ll need 4 locales:

• en : English (US)
• fr : French (France)
• fr-CA : French (Canada)
• en-CA : English (Canada)

side note: this is a ‘pragmatic’ approach to locale naming, where we drop the regional part when it is not needed (more information here).

Great. Now, how do you make your website available in all these locales?

Locales and URLs

The first rule of Search Engine Optimization when you go international is: the locale must appear in the URL. Google suggests choosing among several options:

• URL parameters: example.com?locale=fr
• Subdirectories with a generic top-level domain (gTLD): example.com/fr/
• Subdomains with a generic top-level domain (gTLD): fr.example.com
• Country-specific top-level domains (ccTLD): example.fr

There is no one-size-fits-all approach. The best solution really depends on your specific requirements (this article from Moz may give you some pointers). At Drivy we decided to use ccTLDs because it was the best solution SEO-wise to target different countries. Plus it’s prettier.

First implementation

In Rails this is pretty straightforward. You just need to point your new domain DNS to your application server and drop this code in your ApplicationController (inspired by the official Rails guide):

class ApplicationController < ActionController::Base
  before_action :set_locale
 
  def set_locale
    I18n.locale = request.host.split('.').last || :en
  end
end

We basically take the last part of the URL domain (fr in the case of example.fr) and we set the locale to this value. Simple.

It works, but it has major drawbacks:

• it doesn’t work for ccTLDs that don’t correspond to a valid locale (e.g. example.ca)
• it doesn’t work with second-level domains (e.g. example.co.uk)
• it doesn’t work in dev environment (where you usually use http://localhost:3000)

One other thing that may cause trouble down the road: what if you can’t map a ccTLD to a given locale? This can happen in several scenarios:

• the ccTLD is already taken by somebody else — in which case the next best solution is to use a subdomain
• you want to offer several locales for a given ccTLD (e.g. French and English for Canada)

And this gets even more complex as you add different environments (production, staging, dev) and more subdomains.

There must be a more robust way.

Second implementation

Let’s be more explicit and define a clear one-to-one mapping between the locale and the host:

HOSTS_MAPPING = {
  'en'    => 'example.com',
  'fr'    => 'example.fr',
  'fr-CA' => 'fr.example.ca',
  'en-CA' => 'en.example.ca'
}

Now let’s use this new mapping in our ApplicationController:

class ApplicationController < ActionController::Base
  before_action :set_locale

  def set_locale
    I18n.locale = HOSTS_MAPPING.invert[request.host] || I18n.default_locale
  end
end

We can now easily make this work in our staging environment by using a different hash:

HOSTS_MAPPING_STAGING = {
  'en'    => 'staging.example.com',
  'fr'    => 'staging.example.fr',
  'fr-CA' => 'fr.staging.example.ca',
  'en-CA' => 'en.staging.example.ca'
}

side note: this breaks dev/prod parity, so you should probably avoid this and instead buy a dedicated domain for your staging environment

Same thing for our dev environment:

HOSTS_MAPPING_DEV = {
  'en'    => 'dev-example.com',
  'fr'    => 'dev-example.fr',
  'fr-CA' => 'fr.dev-example.ca',
  'en-CA' => 'en.dev-example.ca'
}

side note: this means every member of your dev team must setup his etc/hosts to make all the domains above point to his/her local machine

One major gotcha: emails

Our implementation works pretty well and is pretty flexible. But there is one big gotcha: what host do we use when we send emails to our users?

The first solution that comes to mind is to use the default host and then redirect the user based on his latest locale:

One big problem: although it is easy to share cookies across subdomains, it’s impossible to share cookies across top-level domains. And since server-side sessions are usually based on cookies this means you cannot have proper sessions across all your domains — unless you implement some kind of OAuth mechanism, which isn’t trivial.

If one our your users signs in on your French website (example.fr) he won’t be signed in on example.com, which means you won’t be able to retrieve his locale and you won’t be able to automatically redirect him to the correct domain. Bummer.

One solution is to use the correct domain in your emails. But since we are sending emails asynchronously we can’t rely on the request object like we did previously inside our ApplicationController.

We can work around this by hacking ActionMailer a bit:

class MyMailer < ActionMailer::Base
  def welcome(user)
    @user = user
    mail(to: user.email)
  end

  def url_options
    super.merge({host: HOSTS_MAPPING[@user.locale]})
  end
end

We retrieve the user’s locale (stored in our database) and we set the default host dynamically. All the links present in the email will use the correct host. It works!

More gotchas?

A few other gotchas to be aware of:

• You must set up multiple analytics accounts, one for each domain.
• You must buy a multi-domain SSL certificate (unless you are ok with managing one certificate per domain). If you want to secure multiple domains AND multiple subdomains things can get very expensive very quickly. At Drivy we chose to use a GeoTrust True BusinessID certificate because it is possible to add up to 25 domains or subdomains for a reasonable price: around €300 for a 5-domain pack, plus €20 per additional domain. This is still very expensive, but there aren’t a lot of alternatives apparently.
• Your SEO juice will be split between your domains — there is no cumulative effect. If you open a new country you will start from zero SEO-wise. One way to mitigate this is to use alternate hreflang.

Despite all the efforts and all the gotchas I am pretty happy about the way it turned out for Drivy. Top-level domains really are a great strategy for the long term as it gives you clean URLs and a strong branding in each country.

If you are unsure about the strategy you want to adopt I really recommend reading this article from Moz as it will give you concrete pointers.

Happy internationalization!

This article is part of the publication Unexpected Token powered by eFounders — startup studio. All eFounders’ startups are built by extraordinary CTOs. If you feel like it could be you, apply here.

You like? Hit “Recommend” and subscribe to our collection!

Making your website multi-regional using top-level domains was originally published in Unexpected Token on Medium, where people are continuing the conversation by highlighting and responding to this story.