When developing a web API it is essential that developers are able to go from 0 to productive in a very short order, think minutes. Fortunately, industry has become very good at this over the past couple of years and API providers are starting to consolidate on a consistent model of what information is made available and how it is presented.
Thanks to SaaS offerings like IBM API Connect or Mashape and open source projects like ReDoc or SwaggerUI it becomes easier for API providers to build attractive and functional points of engagement for developers and developers benefit from not dealing with a plethora of differently formatted wikis!
In terms of this information consolidation there are several key sections that an API provider must offer to help their prospective developers. Here is an example using the Watson Conversation API.
- Marketing material - http://www.ibm.com/watson/developercloud/conversation.html
- Documentation - http://www.ibm.com/watson/developercloud/doc/conversation/
- Sample code - https://github.com/alanbraz/cognitive-head-hunter
- API Explorer - http://www.ibm.com/watson/developercloud/conversation/api/v1/
The above segmentation of information provides an ideal targeting of content to users at different stages of interacting with the API. Here is what each of the different segments strive to accomplish:
Marketing material sells the service at the “end” of the API. This is the first place a prospective developer will land and must explain what the service is and ultimately why it is the best choice. Mentioning that the service presents modern APIs is important (one of many check-boxes a developer is looking to tick off) but of secondary importance at this stage.
Documentation provides the full details about the guts of the service. The documentation needs to focus on the what of the API (key concepts, sample use cases). This is the information that leaves the developer knowledgeable about the concepts of the service in terms of data model and functions. Despite its absolute importance, don’t be surprised when you see your site traffic is actually the lowest for this content.
Sample code proves that the API is as beautiful in source code as it is described in HTML. Generally, APIs will be wrapped with enough business logic that sample code won’t be of great value but it does decrease the barrier of entry for a new prospective developer. Sample code also serves as a quick litmus test of the quality of the service (poor sample code does not build confidence for the quality of the service).
API Explorer is where the rubber hits the road and the developer is provided with just enough information to start interacting with the API. The typical use case would be a developer experimenting with different endpoints and payloads. However, it is important to remember that having developers frequent the API Explorer makes for a great opportunity to cross-sell other APIs (especially those that make sense in the context of the currently viewed API.). A word of caution for API Explorers, if your API depends on very large or complicated payloads then plan to help the use of the explorer construct them in manageable way.
It is important that all of these resources fit together to make a coherent story for the API (and ultimately) the service being offered. Not only does a consistent message across all four channels reduce the cognitive load on the developers but it will also help ensure you perform well in search results.
Have you launched a successful API-centric business where you were able to skip one of the above channels? If so how did you do it? Are there are other essential channels that have been missed?