App & Data Integration 10 mins read

10 keys to a winning API developer portal experience

Read 10 things you need to have in your API developer portal to win over the users (soon-to-be champions) of your API portfolio and make them (and you!) successful!

Brenton House Brenton House

Let’s face it; the end-to-end experience for developers using your APIs isn’t always perfect.

But why is that? What is the difference between an API experience that is a smash hit and one that is not? 

Sometimes, it is based on how the API itself works. If the API isn’t reliable, you’re out of luck. But more often it succeeds or fails based on the website where developers access your APIs. This site—called an API developer portal— is the home base where your users can manage APIs, view documentation, configure security settings, and view resources like documentation, developer assets and a catalog of the APIs themselves.

The problem is, that these API developer portals are often missing features or have features that don’t work.

Optimizing the developer experience on this portal often gets forgotten, lost in the long list of backlog items. When that happens, developers are more likely to just walk away and find another API to use instead of trying to figure yours out.

So, what exactly does it take for developers and architects to fall in love with the entire experience of using the APIs in your portfolio? What does it take to turn users into champions?

I am going to show you the 10 things you need to have in your API developer portal to win over the users (soon-to-be champions) of your API portfolio and make them (and you!) successful! But first, take a look at my webinar below. 

You can watch the full webinar below. Keep scrolling to read the highlights.

heading with wave graphic backgroun

1. Your API platform needs to be intuitive

Everything from your API endpoints, API authentication, API developer portal, API documentation, API code examples should be intuitive. Everything! For a lot of APIs, like REST, gRPC, GraphQL, and other types of APIs, there are some standards. Some of these standards are a little loosey-goosey BUT where there aren’t solid guidelines, there are usually some really good published best practices available. Follow them.

Don’t try to come up with your own custom system for APIs or API portals. Just don’t. Users will come into this with certain expectations based on industry standards. Take advantage of things like OpenAPI, OAuth, AsyncAPI, and Swagger to help you in that process.

Heading text with wavy line graphic background

2. Your API platform needs to be well-documented

How well-documented probably depends on how complex your API platform is. This also goes hand-in-hand with being intuitive. The more intuitive your API platform is, the less reliant on your documentation developers will be.

There are things you can add to your documentation, such as making it interactive. While this might take some additional time in setting up the initial version of this documentation, it can provide a more customized and rich experience for your users.

Another important part of documentation is the changelog. It is very important to document what has changed between versions of your API platform. Don’t just add a bullet point, if possible, but include how these API calls are different or how a task in the API platform will now be performed.

Heading text with wavy line background

3. You need a self-service API developer portal

An API developer portal is often where you will have developers go to do things like managing API keys, creating proxies for APIs, and much, much more. If you are using an API management system, you probably already have some sort of an API developer portal, but that doesn’t mean that there is nothing that you need to do. Most portals include the ability to customize the portal to fit the needs of your organization.

If this is the solution that you are using, you will want to make sure that you are presenting things in the best possible way for your users. If you are using your own custom solution for an API developer portal, a lot of the same rules apply. If this solution is built in-house, you might have more flexibility with what you can change – but changes always come with a cost that includes time and resources.

Zero to API in 5 minutes

4. Provide an awesome onboarding experience

You know what they say about first impressions, right? Well, it’s true. The first experience that your users have with your API platform could make or break your future relationship and affect your bottom line. Ideally, you want your users to be able to go from zero to API in about five minutes.

A user should be able to:

  • Create an account
  • Log in
  • Create an API key or other authentication token
  • Connect to your API
  • In five minutes.

Not every API or product is the same and some are going to be a lot more complicated but, in general, aim for five minutes. I am not saying that it will be some masterpiece ready to go into production. It is just something simple that gives the developer a good feeling for your platform and builds a trust level with you and your products.

If you are taking substantially more time than five minutes, look for bottlenecks and tackle them to reduce any friction that the user might have when onboarding. If you don’t know what your user’s time to first API is, find that out now!

Excellent errors

5.You need to have great errors

I am not saying that your API should be buggy and have lots of errors, but developers are going to try all sorts of things with your API. Things you may not have thought of or maybe things that you have thought of and don’t want them to be able to do. When this happens, you will need to provide error responses that are consistent and well-documented.

There are several different patterns and best practices out there with regards to API errors but be sure you are consistent across your API endpoints. If you are using something like error codes, go ahead and put a URL in the error response that gives the user more context about that error.

Keep it simple

6. Keep things simple

This applies to your APIs and to your API developer portal. Don’t overcomplicate things. Focus on one thing at a time and do it really well. If there is only one possible thing that the user can do given their current state in your API developer portal, then remove or hide the other options. Don’t confuse them but instead guide them to make sure that they are successful (and happy) users.

Also, when you are focusing on that one thing, be sure it is something that is solving a real problem for the user. Don’t add a bunch of unnecessary steps or tasks in a process flow as this will just frustrate your end users.

Don't be ugly

7. Don’t be ugly

There, I said it. Ugly designs can slow people down. This is also directly related to rule number one: API platforms must be intuitive. Really poor design of API developer portals, API documentation, and API endpoints can cause frustration for users. Your API developer portal or documentation might be ugly because of something as simple as a bad color palette. It could also be that you are trying to cram to much information into one screen. Or, that you don’t understand how the users want to use your portal.

Take some time to learn more about your users and good design best practices. And remember, ugliness is not limited to your API developer portal or API documentation. It could also be your APIs themselves. I’ve seen some horrendous naming patterns for endpoints and parameters. It may seem like a small thing, but you might add some love to your APIs by cleaning them up before publishing. 

Show me the code!

8. Show me the code!

That’s right. Developers who use your APIs want to see some code examples for using your APIs. Some include this option in the documentation itself, but others will incorporate it into the API developer portal, where the code can be customized to match the specific needs and configuration of that user.

Either way, you need to include code for a variety of the most used API client languages. Another huge thing related to this is Postman scripts. If you don’t know what Postman is, it is the original (and best) API client / testing / mocking / everything tool for consuming APIs. PLEASE include a Postman collection for your APIs. Use things like Postman environment variables to reference configurable things like API keys, endpoints, and such.

And for bonus points, generate some simple API tests for your calls. This will tell the user what to expect when they make successful (and unsuccessful) API calls to your endpoints.

Logging and analytics

9. API logging and analytics

You may not normally think of logging and analytics as something that is related to developer user experience, but it is. If you have good logging that is available in a standardized way, developers will have access to one more thing that could save you time and resources – and possibly get to a resolved state much quicker.

Related to this is analytics. Some analytics might be available to a user such as number of calls (especially when rate limits are involved), but I am talking about some of the analytics that they might never see. So, if the user can’t see it, how does it benefit the developer user experience?

If you were to:

  • Thoroughly track what API endpoints and methods are being called
  • Track what features were being used in your developer API portal
  • Track what documentation pages were used most often and be able to correlate that to features in your APIs

Then you would then be in the position to know where there might be friction points. Where there might be opportunities for feature enhancements.

You will be able to see what’s hot (and what’s not). Think of it as the developer’s journey through your product. Use this data to give your developers the best possible user experience with your APIs, your developer API portals, and your API documentation.

Free forever tier

10. Free forever developer tier

I cannot emphasize enough how important this is for continuing user satisfaction and relationships with your customer. If your API is attractive to developers, there is a good chance that they are going to try it out before their boss tells them that they need to run an official evaluation of your product.

It might be in a hack-a-thon, side project, or just maybe just because they are curious. Either way, developers will often save this off to have working examples of connecting to your API. As a developer, you never know when you will need it…

But if their boss tells them to evaluate your product and it has been over 30 or 60 days and your product’s trial has expired, this is going to leave a sour taste in the mouth of the developer or architect. Sure, they can probably get on the phone, call your support department, and get an extension to their trial, but let’s face it, nobody wants to have to do that. I don’t care HOW good your support department is.

Do yourself a huge favor and create a limited tier of your product that is free forever. It doesn’t have to have every feature and it can be rate limited but at least your user’s code will most likely still work when they go to try it later.


There is a lot to API developer experience, and this really only scratches the surface. Chances are you are already working on (or have successfully accomplished) many of these keys to API developer experience. But you can likely do more. At the end of the day, the goal is to make the API experience better, and the API developer portal is where it all begins.

Looking for more? Click below to check the maturity of your API program and make sure you are ready to make the most of every interaction.