Let's face it. Not every API Platform works well.
But why is that?
What is the difference between an API Platform that is a smashing hit and one that is not?
Well, there are a few very important factors like making sure it works and that has the features that users of the platform need and/or want.
Sometimes, it is because they are missing features.
Other times, it is because the features that they have, don't work.
But often the API Developer Experience itself gets forgotten. Most realize that it is something important and necessary but when forced to prioritize it in the long list of backlog items, it often gets bumped down to the bottom.
If the developer experience for an API Platform is horrible, users might walk away from your platform instead of being hooked.
What can we do about it?
What exactly does it take for developers and architects to LOVE your API Platform?
What does it take to turn the USERS of your API Platform into CHAMPIONS of your API Platform?
I am going to show you the 10 things you need to do to win over the users of your API Platform and make them (and you!) successful!
But first, let's quickly define a couple of things.
First.
What is an API?
Basically, it is non-human systems that talk to each other in an agreed upon way! Most often, people are talking about Web APIs, include things like REST, GraphQL, gRPC, SOAP, etc.
What is an API Developer Portal?
An API Developer Portal can look different depending on the products that are used but most often it is a website that can be used to manage APIs, view documentation, discover APIs, configure things security, and more!
Okay. Let's jump into it.
10 Keys to WINNING with an Awesome API Developer Experience!
1. Your API Platform needs to be intuitive.
Everything from your API endpoints, API Authentication, API Developer Portal, API Documentation, API code examples.
Everything!
For a lot of APIs like REST, gRPC, GraphQL, and other types of APIs, we have some standards.
Now some of these "standards" a little loosey-goosey BUT where there aren't solid guidelines, there are usually some really good published best practices available.
Follow these.
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.
2. Your API Platform needs to be well-documented.
How well documented probably depends somewhat on how complex your API Platform is.
This also goes hand-in-hand with the number 1 rule about 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.
3. You need to have a self-service API Developer Portal of some sort.
An API Developer Portal is often where you will have the 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 for the APIs that you are managing in that system 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 the users of this portal.
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.
4. Having an awesome Onboarding Experience.
You know what they say about first impressions, right?
Well, it's true.
This first experience that your users have with your API Platform could make or break your future relationship with this user and affect your bottom line.
Ideally, you want your users to be able to go from Zero to Api in ABOUT 5 minutes.
A user should be able to:
- Create an account
- Log in
- Create an API key or other authentication token
- Connect to your API
- and challenge completed!
5 minutes.
Now, I know not every API or product is the same
and some are going to be a lot more complicated but in general, let's aim for 5 minutes.
I am also not saying that is going to be some masterpiece ready to go into production.
It is something simple that gives the developer a good feel for your platform and builds a trust level with you and your products.
If you are taking substantially more time than this, look for your 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!
5. Must 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 in 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.
6. You need to keep things simple
This applies to your APIs and to your API Developer Portal.
Don't over complicate 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 actually solving a 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.
7. Don't be ugly.
There I said it but it's true.
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 you are using a really bad color palette.
It could also be that you are trying to cram to much information into one screen.
It could also be 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.
But... Ugliness is not limited to your API Developer Portal or API Documentation.
It could also be your APIs themselves.
What do I mean by that?
Well, I've seen some pretty 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.
8. Show me the code!
That's right. Developers who use your APIs want to see some code examples for using your APIs.
There are several ways to do this.
Some include this option in the documentation itself but others will incorporate this 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 commonly 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.
9. API Logging and Analytics.
You may not normally think of logging and analytics as something that is related to Developer User Experience but let me show you how it is.
If you have good logging that is available in a standardized way, a developer will now have access to one more resource that could save YOU time and resources but also possibly get THE USER 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 this, how does this benefit Developer User Experience?
If you were to thoroughly track what APIs endpoints and methods are being called,
If you were to thoroughly track what features were being used in your Developer API Portal,
If you were to thoroughly track what documentation pages were used most often and be able to correlate that to features in your APIs,
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.
10. Free Forever Developer Tier for your API Platform.
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.
Conclusion
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 don't forget about them.
Take the time as a team to review these and make sure that your APIs (both old and new) as well as your API Developer Portal and documentation is equipping developers and other users to be successful!
Feel free to connect with me on LinkedIn and ask me any question or share your experiences with APIs! I would LOVE to hear them!
https://linkedin.com/in/brentonhouse
About Brenton House
Brenton House is Vice President of Digital Evangelism at Software AG. As an API and Digital Transformation Evangelist and Strategist, he has connected enterprises with API solutions and microservices, to help drive innovation and overall business growth for many organizations.
In his 25+ years of experience, he has worked across many industries including broadcasting, advertising, retail, financial services, supply chain, transportation, technology, and publishing -- gaining a breadth of knowledge on all things APIs and Integrations. His diverse experience set and unique creative skill sets have enabled him to equip organizations in creating captivating and innovative products that delight users.
Check out some of our other resources to continue learning more about APIs and Integrations!
⭐ Software AG Blog ▪ https://blog.softwareag.com
⭐ API Knowledge Portal ▪ https://knowledge.softwareag.com
⭐ Software AG Tech Community ▪ https://techcommunity.softwareag.com/
🎬 Software AG YouTube Channel ▪ https://youtube.com/softwareag
🎬 Brenton House's YouTube Channel ▪ https://youtube.com/brentonhouse
🎬 API Shorts YouTube Channel ▪ https://youtube.com/apishorts
👇👇👇 FREE online API Maturity assessment here! 👇👇👇
Top comments (0)