How to Make A Rickdiculous Developer Experience For Your API
How do you make a stellar developer experience (DX) for API integration? Not by sharing docs in a PDF, that's for sure. Let's consider things from the developer's perspective and walk through some expectations and common hangups when integrating with REST(ish) APIs.
Along the way, we'll reference Zuplo's sample developer portal for the Rick and Morty API as an example of developer experience done right. So, sit back, flip on interdimensional cable, and see how to make your API like 'wubba lubba dub dub' for developers.
Tell me what this does#
"I should be able to tell what your API does from your landing page."
A developer should be able to instantly grasp the functionality at first glance. They may lose interest immediately if you're not using the right keywords or description. So, put things in plain English. Make it simple so that even a Morty would understand.
Show me the code already#
"I'm sick of your marketing fluff and just want to make an API call."
A quality developer experience has onboarding optimized to the 'T' — so reduce your time to first call (TTFC)! Code samples help get to 'Hello World' instantly. For instance, the Rick and Morty API docs can generate calls for all major languages, like Curl, Python, Ruby, JavaScript, Java, C#, Go, PHP, and others.
Make generating API keys painless#
"I don't want to deal with complex auth, just give me a key."
Automatically generate an API key for new accounts. Done. Also, don't assume developers know how to authenticate or where to place tokens in the HTTP request. Have an authentication guide and point to an example. Better yet, integrate this into your playground…
Keep in mind: API keys tend to have better DX than JWTs. This article on API keys explains why.
Have a playground in the docs#
"I should be able to test your API directly in the docs."
Enough with static API documentation! Put a live playground in the docs to generate requests for all your methods. Make it fully functional, and auto-populate it with the developer account's API key. For example, the Rick and Morty API docs offer a playground with a one-click copy-and-paste button and an autofill ability for parameters — goodies that help developers get schwifty.
(Honestly, playgrounds like this should be a standard API developer experience, but surprisingly, they're still rare).
Better yet, get it in my IDE#
"Wait, why isn't this just a VSCode extension?"
But why make developers visit a third-party site for docs? Context switching rips them out of the flow state and decreases developer productivity. Instead, try to get closer to where they already work. This could be a VSCode extension, like VSCode Twilio. Using Postman Collections or generating SDKs can also help put things in scope.
Make sure your OpenAPI spec matches production#
"OpenAPI should make APIs more predictable, not unpredictable."
An OpenAPI definition can greatly help API integration, but some specs feel like they're living in a parallel universe. Unfortunately, spec drift is an all-to-common scenario among APIs that don't use design-first development. Undocumented subtle mechanics, like rate limits, performance lags, or random behaviors, can also cause broken functionality.
Two cool perks of the Rick and Morty reference: 1) it uses an API gateway that runs OpenAPI natively, which means that if you want to change the API, you do it by updating your API reference. This way, it's extremely hard to introduce drifts. And 2) It offers an API endpoint to return the OpenAPI file for the API. That's so meta it's rickdiculous.
Take things to the multiverse with AI#
"Sholudn't AI just automate all this glue code nonsense?"
Ricktastic programmers already have an artificial assistant like Diane, automating much of their coding in general (you might call her Copilot or ChatGPT). Ideally, AI also does the heavy lifting of generating requests to popular web APIs.
In the future, it'll be more common to tell any API a command in natural language, something like "get user info from new signups in the past 24 hours," to produce and issue an accurate HTTP request. With the dawn of LLMs, API providers have the technology to add AI-driven features like this into their developer centers.
Regardless, public LLMs are already ingesting your public docs and tutorials on external forums, with some pretty decent outcomes. Still, it's a good idea to prepare your dev resources to be consumed by LLMs to avoid hallucinations.
Be consistent#
"No surprises, just work as expected."
Don't make your API like Morty's Mind Blowers — constantly changing and impossible to keep track of what's going on. Instead, APIs should be functional and designed in a clear way.
A consistent style will greatly help DX, especially if you have multiple APIs. (Kristen Womack from Microsoft calls this "Familiar Hallways"). So, use consistent styling, naming, and casing across your methods and endpoints.
One way to evaluate consistency is with a schema scanning tool like RateMyOpenAPI.com, which will rank your design and performance against established best practices.
Creating a rickdiculous API experience#
You don't want your API to be like being stuck in Jerryboree — boring, uneventful, with no real value. Instead, you want users to be constantly impressed. As part of that, your developer resources should be like a portal gun, opening up endless possibilities and instantly taking users to inspiring places.
Here are some other tips for creating rickdiculous API developer experiences:
- Have error messages that actually help. Don't let developers get riggity riggity wrecked debugging issues. Produce human-readable error codes that offer actionable guidance.
- Don't change things without telling. Establish consistent versioning and deprecation procedures. Communicate any breaking changes, or face the Council of Ricks for your transgressions.
- Let me test it for free for a while. Ever heard of freemium? Developers should be able to get up and running and use your API in production for a bit to test how it works for free.
Lastly, the community around your API should be supportive and squanchy. Have a way to collect developer feedback and act on it to refine the experience. This will help you create killer developer experiences that are on the level of science fiction.
