Build Your API First

I have a beef with companies that don’t expose nearly everything their product can do with an API. I get anxious wondering, “why can I only do some of the things via the API? How is this sausage made?” Sure, there are plenty of examples of endpoints that shouldn’t be exposed, such as changing passwords probably should be kept private. Regardless, there are tons of examples of products that I can type in a field in the UI, but that field isn’t available in the API. I can perform an operation like archiving, but doing it with a simple HTTP request with an Authorization header? Forget it.

This isn’t an attack on inadequate (or non-existent) APIs, but rather why choosing to go API first from Day 1 will be a game-changer for your business, and the decisions we made at FireHydrant to do this.

The Frontend Matters

Users expect a dynamic experience on the frontend now. This expectation likely comes from their experience with Facebook, Netflix, and other large tech firms with the resources to invest in complex frontend architectures. It’s a sad reality, but if your website just doesn’t have a particular type of fancy sizzle to it, customers may think it’s “cheap.”

Dynamic frontend experiences provide a sense of quality. It’s the same feeling you get when you hear an excellent thud when closing a car door. Serving plain old HTML with no automatic updating in the UI just doesn’t cut it anymore.

This is a hurdle for young companies, many with little or no funding, vying for people’s attention. You want to move fast and create. But adding layers of React, Redux, GraphQL, a complicated backend… it hurts to even think about doing it when you have no customers.

It’s a tough choice for companies just starting out with their software offering. Do you go full frontend / API, or do you go as fast as possible, and add the API later?

(Hint: Most add the API later.)

How we designed a company with an API first mentality

When we raised our Seed funding, we had no idea what the future really had in store for us. Every start-up operates under constant uncertainty, and we’re no different. My co-founder and our Head of Product, Dylan, slept on my couch for 6 months to get through this time. But a choice we made early on has compounded in interest, and I don’t think we’d do it a different way ever again:

We decided to build a JSON API, a React+Redux frontend, with Swagger 2.0 documentation, for everything.

We’re using Ruby on Rails for our core application, so in a way, much of this wasn’t actually tough to do. We use Grape for our JSON API and React, Redux, for our frontend. When we build something new, it gets a new API. When we need to toggle the state on an object, it gets a new endpoint. New object type? New JSON entity descriptor.

This discipline has amassed a substantially extensive JSON API for a company that is just over a year old, with 131 endpoints as of writing. All of our runbooks, severities, service catalog, and even the status page subscription endpoints, have an associated API.

The benefits of going API first

We’re not stapling an API to a tree and hoping it behaves the same way as our UI. Our validations will be the same, pubsub events occur the same way, even security checks stay the same. I’ve been at multiple companies that haven’t done this, and I’ve never seen it end well. The inconsistencies that your customers will face when you build an API years after the main app will madden them the point where they tweet at you, constantly asking, “why? why did I deserve this?”

We’re trying our hardest to avoid this entirely. We’ve even built the API with the concept of bot tokens, as well. This means actions can be performed against the FireHydrant API without a user. If a user leaves your organization (they will), your API integrations shouldn’t break with it. Everyone has seen the dreaded “{Insert integration name} has been removed from this channel” in Slack when someone leaves the company.

Mobile applications are in the playing cards for us, too. And because our APIs are built and then consumed by our frontend engineers, it’s a good litmus test before we ever give it to a customer. Best of all, customers can integrate with us and expect the same level of care our UI gets.

Let me repeat that.

Customers can integrate with us and expect the same level of care our UI gets.

Because we build our UI on top of the same APIs, that means users get a greater sense of stability. Our APIs aren’t an after-thought; they are the thought.

Greenfield is kind of cheating

I’m not ignorant to the fact that we had a leg up: we could start the company this way. Most folks reading this will not have that advantage. But the benefit of shifting mindset to an API first mentality will compound in interest as your company moves on. FireHydrant can build and deploy features faster than anyone else in our space because of these types of decisions.

The fact is, we knew this adventure was a risk from the beginning, but we operated under the assumption that we were on to something. When we started to get out of the trough of despair that all startups see before growth, we were prepared with a well-built API that we consumed ourselves, and therefore anyone could. We made a bet that we weren’t dying anytime soon, so let’s do it the right way now.

If you have the confidence to build an API at all, you owe it to yourself and your customers to build it first. You should be able to tell your customers (jokingly) “If you hate our design, our API has everything you need to make your own interface.” Also, from a business perspective, if you’re not investing in an incredible programmable interface to your product, you’re losing out on millions (yes, millions of dollars) in long term revenue. Customers that integrate with you are now more than customers, they’re partners.

Build the API, and then build the rest of the feature on that API. It has long term gains, customers can integrate more effectively, and best of all, you don’t have 2 branches of logic to maintain.