By: Rob Zazueta
When you create an API, you’re inviting developers to become your customers. Even if your API is exposed only internally or to high-value partners, or if you’re only working with the business development teams at your partners’ companies, your end users are developers. And just as you spend the time, money and effort to provide the best user experience through user interface design on your website, you should expend the same level of time and effort to provide the best possible developer experience through API design.
Developers have a reputation for being a finicky bunch. When you consider the pressure they’re under to deliver stellar products on tight deadlines and within tight budgets, it’s no wonder they’re picky about how they spend their resources. If your API is poorly designed, poorly documented and poorly supported and they’re not required to use it, you can bet they won’t. If the project they’re working on does require using your API, be prepared to field frustrated emails, exasperated calls and escalations through management on both sides of the integration.
The programmers building your APIs are under the same time and money constraints, and they’ll frequently take shortcuts to get an API up and running quickly. One of the most common shortcuts is to use a popular framework like Ruby on Rails or CakePHP. Both of these claim to make building a RESTful API so easy that developers practically get it for nothing. The APIs generated by these frameworks do work well and are a fine solution when the APIs they generate are guaranteed to only be used by the developers creating them, but they’re tightly tied to the internal design of the application with little regard to RESTful best practices or emerging standards.
Rather than rely on automatically generated APIs, you should give your programmers the breathing room to spend time really considering the final design of the API. RESTful standards remain fluid, which can be frustrating when trying to decide how to present API data in a production environment, but staying informed of current best practices can make this an easier process.
Great developer experience begins with great API design, which is reflected in great documentation. Our I/O Docs system allows developers to begin making calls against your API within minutes of receiving an authorization key. Programmers can preview and test calls and see the output they can expect without writing a line of code, saving them valuable time and encouraging them to explore the full value of your API.
Even if your API never sees the light of day outside of your organization, new developer hires are on-boarded and brought up to full capacity more rapidly when they work with well-designed and well-documented internal APIs. It also encourages them to stay with your group longer, reducing churn and improving the morale of your entire engineering team.
We care deeply about developer experience here at Mashery. Our Strategy Services and Developer Outreach teams can help your engineers produce an API that delights their peers while accomplishing your company’s goals. Drop us a line to get started.