One of the best parts of my job is working with companies on their API strategy. You learn a lot about them that way. Opening up services with an API is more than an engineering project. For most, it’s a new way of thinking about their business.
And having seen these projects close up, I can tell you that certain approaches to APIs work, and others work, let’s say, less well.
Even experienced developers tend to fall into a short-term mentality when building APIs. It usually goes like this. They work backward from the application to arrive at the spec. They start a whirlwind of coding, check the boxes on features and functionality and bring in the project, hopefully on time and on budget. Well done and off to the pub, right?
Not quite.
What could possibly go wrong?
This isn’t Field of Dreams. Just because you build an API, that doesn’t mean anyone will use it. If you’re not designing your API to delight your consumers - in this case, your developer community and even your own team - you’re setting yourself up for failure. It’s as true with an API as it is with a smartphone.
The most successful API projects take what I call a “design-first” approach. Fundamentally, design-first is about creating an experience that delights your audience. Before writing any code, think about the people who will use your API. Ask yourself: “Am I creating an experience that will attract a community, inspire engagement and provide value?” Most of all, “Would I want to develop with this API?”
Here’s how to make sure you can answer yes to those questions.
Design for consistency
Planning too little is dangerous. But so is planning too much. This isn’t a science experiment to find the ideal design. Perfection isn’t the goal: consistency is.
Do your users a favor and settle on well-defined patterns and common design elements you’ll use again and again as your application evolves. If you have two teams building two APIs for your software, users shouldn’t be able to detect any difference.
Security should behave the same way. Versioning, URL schemes, API keys and error codes should look and work the same in all parts of your API. The same goes for querying and receiving data. These might seem like the basics, but they’re so rarely followed in practice—and so powerful when they are. Planning out your API with a modeling language like RAML can help you stick to best practices.
If you need another incentive to be consistent, remember that you’re doing yourself a favor too. All the work you’re doing on your API right now, you’re going to do again someday. Maybe at the moment you’re building a native mobile app. Over time, you’ll want to add features. You might want to support different platforms. When you do, the last thing you want is to spend time rearchitecting your API. A clear, consistent design will serve you in good stead over the lifetime of your application.
Design for scale
Your API needs to be built to last, but planning for growth can be tricky. You can’t invest too much in scalability until you generate the traffic. But you need to invest enough to grow without affecting your users. It’s a delicate balance.
The easiest solution is to publish your APIs on a cloud platform, where scalability is built in. That way, if you get spikes in activity, your service won’t crumble under the load.
You also need to choose your API management platform carefully. It can’t be an afterthought. It’s a powerful tool to ensure that all your users have a good experience. It allows you to prescribe in great detail how you API will be accessed. It provides a safe, secure experience for end users, and gives you visibility into how the API is being accessed. It’s Mission Control for your API, and you can’t neglect it.
Design for people
Having said all that, developers are the single most important factor that determines the success or failure of an API. No matter how elegant your code, it won’t be enough to make people engage.
People don’t want to think too much. Software design practices can get wrapped up in the quagmire of edge cases; the litany of possible things a random developer might do one day. Define what you can do with the API and what you can’t; leave the kitchen sink in the kitchen. The process of design should direct focus. It’s better to start narrow and broaden over time. It’s also critical to explicitly define the boundaries of your v1.0 API so developers have context of what to expect.
You need to be thinking about the engagement experience of your API up front. Once you’ve launched, you need to help developers discover your API and succeed with it through documentation and tutorials. You need to promote it, gather feedback, involve the community in improving it. An API needs to evolve, just like the businesses it supports.
Want some good examples? Take a cue from companies like Stripe and Twilio, where their API is the product. If they don’t attract a community, their business goes under. You can bet they’re getting engagement right.
In summary
Creating a strong API strategy is a challenging, exhilarating experience. It forces you to think not just about what your application is like now but what it will be in the future. If you keep your focus on user experience through good design up front and plan for the long term, you’ll have an architecture that can support your digital business for years to come.
- Ross Mason is Founder and VP of Product Strategy at MuleSoft.
