Developing A Great Developer Portal

For more information on API design strategy, tools, and best practices, you can download the API Provider Guide – API Design.

This report also includes a listing of vendors who provide tools for API Design, and was prepared by Kin Lane of

Our customers are always looking to improve the success of their API, and one of the best ways to do this is to provide an excellent developer experience. The front line for your developer’s experience with your API is your developer portal – so while it may seem like a lot of work to set it up, you’ll save enormously in support costs and help keep developers engaged with your API.

So what’s a great developer experience?  Twilio aims to make sure that a new developer visiting their site can make their first call to the API within 5 minutes. Remember, whether your customers are internal to your company or out in the open API ecosystem, their time is valuable. The best way to show that you respect this is to put all the information they need to get started right in front of them.

The items you most want to have on your developer portal are, in descending order of priority:

  • Use Cases
  • Example Code
  • Getting Started
  • Documentation
  • API Explorer
  • Pricing

Use Cases
When a developer comes to your site, the question that’s likely at the top of their mind is “Why do I care about this API?”  You need to let them know right up front what they can do with the API, how they can use it, and what you’re hoping they’ll build. Showing use cases will start a developer’s brain churning with the possibilities and help get them excited about what they can build with your API. If they have questions about *what* your API does, use cases are the best way to describe the pieces of functionality in a meaningful context. This is one of the places where you can make your portal really stand out – many API providers don’t think to include this, but developers really appreciate being told what kinds of things are possible.

Example Code
Developers are somewhat tricky to market to. You may have the snazziest looking developer portal in the world, but it will lose out to another API with a simpler portal that provides developers with example working code. If you want to create and provide an SDK it’s definitely an option, but you should still show how to access the API directly (if possible) and have code that demonstrates simple reads, writes and searches. It should be completely functional and provided in multiple different programming languages. Most web developers are familiar with PHP, Python and Javascript, so those are great languages to target – if you know that your API will be used by Java or C# programmers then you should provide examples in those languages. Remember, the goal here is to give the developer something they can just run to connect to the system.

Getting Started
This is where you can grab those new visitors and really impress them. Provide a tutorial that takes a user through the process of authentication and then performs simple reads, writes and searches (similar to the example code – in fact you can use that code here as well). Make it easy to get through the process and provide lots of encouragement throughout your getting started guide. While this is aimed at new visitors, it’s still a good idea to put this on the front page – your return visitors will dive right into the section they need and ignore the things that don’t apply to them, but new developers can get overwhelmed by too much information if there isn’t an obvious path to follow right on the home page.

Of course, you need documentation for your API. Make it clear and easy to follow, show exactly what the calls are and what they will return. Cover error messages, what they mean, and how to handle them. Ideally you’ll have documentation not only for what the API does, but also how to do specific tasks (the use cases are a great place to start). Don’t be afraid to create a few guides to tie together the rest of the documentation – explaining how search works or what to do for authentication frequently require more than a simple page, and the developer will be grateful that you took the time to explain the more complex topics.

API Explorer
This is a nice way to engage developers who are new – in fact your getting started guide can leverage it to show how to explore the API. For some developers, this is the best way to learn what an API can do and what the call/return structure look like. The explorer should show the exact call and what the live response is from the server, including headers for both the request and response. This tool can also help developers to debug issues they’ve encountered, by providing example successful calls to compare their broken calls against. There are multiple tools providing this functionality – one of the best strategies for choosing one is to find a portal with a good console and use that tool for your system.

Pricing (for open APIs)
Ideally you’ll have a free tier for users who are just browsing your API – even if you have a trial period, many developers will shy away from a system that requires that they give a credit card. A developer may have some time to work with the API and then get swamped with other tasks before he can come back, so a 30 day trial period can go by without them being able to do anything. If you can’t have a completely free tier, consider extending the trial out so that it’s “X time after the first successful call,” and realize that you will still lose out on developers who don’t want to engage in a system that can’t be explored for free.

Most developer portals don’t have the above items (or they just have documentation), which is a shame, because it increases developer frustration and support costs while making it more difficult to understand the goals of your API. The Primal API has a great developer portal featuring all of the above – I encourage you to check it out and see. is a new API, still in beta, and their developer portal has some of the listed items, but with use cases, documentation and an API explorer they’re still way ahead of many of their competitors.

Again, the items above are ordered based on what’s most important. Even if all you do is add a few use cases and a simple getting started guide to your documentation, you’ll have made the experience much better for your developers. Be sure and get the most out of your developer portal, and watch your API rocket to success!