10 Keys to a Great API Developer Experience!
Brenton House
IBM ★ Top Voice { cyber + ai } ?? 500K+ YouTube Subscribers ? keynote speaker ? ex-hacker ? digital influencer ? #ai ? #cybersecurity ? #redacted ? #apisecurity ? #integration
Let’s face it. Not every API works well and not every API product is loved by users.
But why is that?
What is the difference between an API Portfolio 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 API 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 your API products is horrible, users might walk away from your platform instead of being hooked.
Watch this short video on the keys to a successful API Developer Experience for your API program!
What can we do about this problem?
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 Products into?CHAMPIONS?of your APIs?
I am going to show you the 10 things you need to do to win over the users of your API Portfolio and make them (and you!) successful!
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” are 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 the API documentation is the changelog.
It is very important to document what has changed between versions of your API products. Don’t just add a bullet point, if possible, but include how these API calls are different or how a task in the API product 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:
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.
?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
Feel free to connect with me on LinkedIn and ask me any questions or share your experiences with APIs! I would LOVE to hear them!
--------------------
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! ??????