Web APIs have become ubiquitous in the industry, but many organizations are struggling to create platforms that are attractive and engaging to developers. Creating an API that developers want to use is not a simple task—it requires mindful planning and implementation, as well as some careful thinking about communication with the client developers. Additionally, the API needs to be designed with the developers in mind—developer experience is the first priority.
A strong Web API provides a very specific and understandable business value for the company, whether it is increasing usage, solidifying partner integrations, or enabling new applications to access their system. Whatever that business value is, it should be communicated clearly and consistently to the developer community. Developers who understand the goals of the platform will understand better what they can and should do with the platform to work in synergy with the organization. Similarly, the targeted use cases need to be outlined for the client developers, with clear tutorials, sample code, and effective support.
Many companies are still having some trouble letting go of their fears about losing intellectual property. Instead of being worried about the dangers of sharing information about the platform, organizations would be better served to turn the topic around and communicate everything to their developers in order to strengthen their platform and recruit developers as evangelists for their platform.
On the flip side, keeping this information hidden from developers leaves them to attempt to find their own way. Frequently, this can lead to situations where clients use the API in an unsupported way or developers create clients that don't fit with the organization's product goals.
Communication of this sort is one of the cornerstones of an irresistible API. While past systems worked well with cards held close to the chest, a web API is going to expose a great deal of information about your system whether you share it directly or not. Take the time to explain your platform goals and ideals to the developers who consume it. Think of these developers as your partners, not as potential competitors.
What else makes a web API irresistible? Deliberate design. A successful API will be created with use cases in mind—these specific tasks should be easy to accomplish with the API, documented clearly, and understandable to any API client developer. In order to create a consistent platform, it's best to take the time to model the schema before the code is written. Schema models provide a human-readable description of the API, suitable for discussion with product managers, other teams, or even the customers who will be consuming the API.
A great web API will also have open source sample code, helper libraries, and example applications available for developers to use as building blocks. The easier it is to get started with the API, the more likely that developers will become engaged with the platform and create strong client applications. Open source is an amazing thing, and seeding your community with great code will encourage other developers to add their own contributions to the ecosystem. Answering questions well in a form will bear fruit as your developers start answering the questions of other developers, further strengthening your community.
The path to creating a fantastic API can take many forms, but there are a few guiding principles that should always be followed. Platform usability should always be of paramount importance—aim for the best possible developer experience. Documentation needs to be complete, including tutorials and guides to help developers get up and running quickly. And most importantly, the information shared with client developers should always be clear, consistent, and complete so that these valued partners can work with the platform team to help create an amazing, first-class API.
I will be speaking on Irresistible APIs at Great Wide Open on March 16-17, 2016.
Comments are closed.