Six Ways to Make Your Developer Portal More Intuitive

For many APIs, a Developer Portal is the first interaction a developer will have with the API. Typically, this is where a developer finds Documentation, code examples, an app gallery and other details that connect them with the API provider. If you want developers to use your service, you'll aim to make everything within the developer portal as clear as possible. Consider these six steps to bring clarity to your current and future developers.

1. Ensure developers can find your portal

This one seems obvious, but most APIs aren't even able to achieve this level of clarity. The reasons most fail are various, but it's usually related to the many other priorities within an organization. Most companies can't put the link on the header of every page, unless the entire company is an API. Though API businesses are becoming more popular, most APIs play a supporting role.

If you can't provide a header link to the API, consider a footer link. Or give the API a mention on the home page. At the very least, mention the API on a page that is one click from the home page. If you aren't able to give it that much visibility, you might ask whether it makes sense to have your API public at all.

You can also make your API easy to re-discover by using one of the common API portal URL styles.

2. Let developers see a complete API Reference

When developers visit your portal, especially for the first time, they want to quickly determine whether your API can fill their need. A complete API reference helps communicate your API features in the most efficient way. Longer form content absolutely has a place, but you should make "just the facts" a click away.

Common API portal annoyances include a registration wall between the developer and the API reference. Or worse, if you make a developer wait to talk to someone or be approved, chances are you'll never even know the developer was interested.

And provide the API reference in a fully web format (i.e., no PDFs, please) and all on one page, if possible. Again, you're looking to save the busy developer's time.

3. Create an API explorer

It used to be a fancy, advanced feature for developers to be able to make live calls against your API. Now it's an expectation. An API explorer provides your documentation with form fields to add data to create requests. Developers can click a button and see the API response appear right on the same page.

If you can provide an API explorer without registration, that's great, but not always feasible. There's an open source API explorer that can get you started.

4. Provide client libraries in popular languages

Many developers will want the opportunity to make direct REST calls to your API. However, to inspire speedy integrations, you should make wrappers in the languages your potential developers are most likely to use. These small bits of code turn API requests into Function calls right from the code.

PHP, Python and Ruby are among the most popular API library languages, but it's important to choose based on your own audience.

5. Write extensive sample calls and example code

Documenting the API and letting developers play with it on your site goes a long way, but remember we're a lazy sort. Give sample calls and example code that are copy-paste-able. It's not that developers want you to write their apps for them, but this helps to accelerate the time to first hello world. Once a developers have something--anything--running they're a lot more likely to tweak and play--to use your API.

Take it a step further and provide entire sample applications as open source. Even if it's just a simple hack, an entire hello world app can get developers on their way toward what they want to build.

6. Support industry best practices

This final item can go a long way toward getting your API adopted. Even if you've checked off the other five steps, if developers judge your API to be "weird," they're likely to go elsewhere. The most common way you'll see API providers do this is with Authentication.

Even though OAuth 2.0 comparisons show there are differences in the standard's implementation, it makes more sense to go with OAuth than to make up your own or choose something more obscure.

The same goes for protocols, data formats, client Library languages and anything other popular industry trend. If you get creative, you may lose developers who are looking for a service that fits well with their existing integrations. That's really the over-arching message of these six steps to a clearer developer portal. You want to make it easy for a developer to choose your API and get started.

Adam DuVander is Developer Communications Director for SendGrid and Contributing Editor at ProgrammableWeb. Previously he edited this site and wrote for Wired. You can follow him on Twitter.

Be sure to read the next Best Practices article: MuleSoft CTO Touts Advantages of API-First Design