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?
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.
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.