API consultant Leah Tucker shares her ideas on designing APIs with the human experience in mind.

A common question I heard at Nordic APIs Platform Summit in Stockholm and API the Docs in Amsterdam: what makes a developer portal successful? I’m going to attempt to answer it here. And I encourage other sassy experts to chime in for good, old-fashioned debate in 1-2-3.

1. The goal of a developer portal is to help your developers quickly build an app. Right or wrong, people?

Let me start with my background. By day, I work as a software integration engineer for my company — {your}APIs. By night, I work on other fun stuff, exploring API integration for mobile apps. I’ve worked as an employee or consulted as the product owner of an extensive enterprise API deployment program, API developer portal, API architect, and API technical writer. Before that, I was a web developer. The point is, I know a great developer experience when I see one because I’ve worked the whole lifecycle of APIs.

I’ve touched thousands of APIs, and I’ve designed and documented hundreds. I am quietly ruthless. Ruthless with how well an API is designed and documented. I am politely unforgiving. Unforgiving of any pain I might experience integrating your APIs, particularly across multiple API collections within a company. So when I tell people what I do, I like to say, “I anticipate the human experience of APIs.”

Here are some elements I find most critical to building an API-driven mobile app:

1. Easy registration (to get an API key). Email, full name, user name, password. That’s it. Don’t make it painful. Make it easy. Even better, allow developers to enter only their email to sign-up. Send them a branded account activation email with a click “Activate” button. Upon success, direct the user to their user dashboard to get their API key.
2. Visual ‘Try it out’ functionality (app features). Don’t force developers to sort through your API request/response parameters line-by-line. Allow them to see it in action! Use drop-down menus for the request filters/parameters and show them a real-time demo to see the effect.
3. Pricing. Let developers start for free (with access to all of your APIs) but show your production pricing! And simple pricing models, please. A startup company needs to assess costs for go-live, ‘do I need more funding?’ ‘Is there a commitment?’ ‘Dare I say, can I purchase transaction upgrades on your developer portal, please?’
4. Limits/Throttling. Again, ‘what do I get for free and what happens as I grow?’ ‘Can I see my API transactions on your developer portal, please?’ Again, constantly assessing costs.
5. SDKs. ‘How much time is it going to take to develop this thing?’ If you have SDKs, hardly any time at all! As long as the API documentation is in step 1-2-3. Developers don’t come to your developer portal expecting to read a book; they scan.

—MILESTONE—

The developer has decided to give your APIs a test run. They’ve created an account. You’ve helped them identify pricing. They can now visualize application features and have SDKs to implement them.w

2. The success of a developer portal comes from the ground up. (You, API technology provider)

Above we laid out the five critical elements to help a developer quickly build an app. Neat-o! And where did all this come from, again? It certainly wasn’t magic. It is built from a lot of work that started from within the company—yours (API technology provider).

Here is what’s needed internally for you to create these 5 critical elements.

Easy registration (to get an API key)

1. An API (generally) on the back-end to create, store, then pass these client credentials to your developer portal.
2. How many APIs do you have again? All API product managers need to be onboard with open access. If not, that requires organizational change and internal messaging from higher-ups.
3. Your portal must also follow GDPR rules. Full name, user name, and email is a “low risk” category, but your legal team must draft the terms and conditions for what you collect.
4. As part of GDPR, you’ll also need to encrypt user data in your developer portal team’s local IDEs. And provide your users a way to opt-out of website tracking (e.g., Google Analytics), and un-publish their data from your user database if they cancel their account.
5. Your content/technical writers should have created the copy for the account activation email.
6. Your corporate branding department probably wants to approve the color palette you use in the email.

Keep in mind; this covers only a foundation for user registration. The turnaround could take up to a year. It does not include frontend development.

Visual ‘Try it out’ functionality (app features)

1. Let’s assume for simplicity that you’re using Swagger UI, and your specifications are using Open API (a.k.a. Swagger) 3.0. You’ll need to have either autogenerated or created all of your specifications manually. I’ve not had much luck with the accuracy of auto-generators. (If you’re reading this article, spill your secrets if you know of a tool or process).
2. Let’s assume the above process is manual. Do you have the skill set within your organization to create these? You’ll likely need to create these on behalf of your API teams, review for accuracy, then have those teams review the specifications again.
3. Your API teams may have no investment in the business decision to build your fancy developer portal. If you create the specifications on their behalf, you have between “now” and the time they version-up their APIs to get these teams to maintain their specifications. Again, this may require organizational change and internal messaging from higher-ups. Let’s assume success with this initiative.
4. Your Swagger specifications are now part of your developer portal. How good is the documentation? It’s now front-and-center. Most users (except the most skilled software integration engineers) will consider it part of your portal. Inadequate documentation will affect user opinion (e.g., net promoter score) of your portal. You may need technical writers to work with your API teams. And can they continue to maintain this level of quality once you hand it off? Again, organizational change and internal messaging from higher-ups. Let’s assume success again.
5. Finally, the demo aspect that allows users to see the effect. You’ll need to integrate each API into its mini front-end web application. What happens when you release a new feature? (Note: get feedback on your APIs from this integration team, whoever they are. Particularly on documentation.)

Pricing, limits, and throttling

1. Do all of your customers get the same price for an API? Limits/throttling? Are there different pricing tiers? Are you allowed to list these tiers publicly?
   All these factors affect the organization and documentation differently.
2. Your content/technical writers need to provide documentation, regardless. Otherwise, not having clear answers will impede the app-building process, negatively affecting the overall user experience and opinion of your portal.

SDKs.

1. There are many different ways to create an SDK, including from scratch. It could become costly to develop and maintain. Let alone for your technical writers to document each upgrade. In step 1-2-3, remember? Much more difficult to document in as few words as possible.
2. Before you go down this (often pricey) road, do a little research. Figure out the most popular programming languages your customers are using, and the most common use case for the type of applications they are creating. For example, a mobile app developer would prefer to use React.js because it’s compatible with both an Android and Apple app store launch.

Whew! Your API developer portal team, your whole organization, and your executive advocates have a lot of work ahead.

3. The success of your APIs comes from your well-oiled API machine. (You, API technology provider)

From your design strategy.

I can’t think of a single company that didn’t start with one “A-team.” This is a single software engineering team deploying all APIs for a proof of concept to test the market. I often hear this when approaching the concept of a standard data model: “We’re fine. We don’t need to think about a common data model. It’s just us.”

Indeed! This philosophy often works when there’s one team doing all of the API development. However, it’s not scalable.

• Think two years into the future when your API program is officially created, and more teams begin to join the mix. Unless a design strategy has been implemented, the net result will be that each side is designing their APIs in a silo.
• Over a few years, this will create a data divergence where APIs within the same company eventually become incompatible with one another. For example, different means of authentication, data elements, status codes, error responses, even product, and endpoint naming.

At this juncture, your customer is forced to handle all of your design discrepancies within their application, which leads to a stack of technical debt. And a whole lot of work. For an application that uses raw API calls, this becomes a nightmare to maintain.

Fast forward two years. Three API teams have each developed 20 APIs for the “hotels” domain with good adoption from their customers. A new customer enters the mix and wishes to combine APIs from all three teams. The problem is that each of the APIs returns a different data name/format for the hotel check-in date parameter:

1. hotel_search: “checkInDateTime” as 2019/11/01_17:20:28+00:00
2. hotel_details: “check_in_date” as 2019-11-01 + “check_in_time” as 17:20:28+00:00
3. hotel_book: “check_in” as 2019-11-01T17:20:28+00:00

Your application developers are now forced to convert the format within their application backend for each of your endpoints. Call to call. How punishing!

• Their application calls hotel_search to display results to the user.
• The user “clicks” on one of the hotels for more detail. The check-in date needs to be parsed, converted, and passed to the next request in hotel_details.
• The user goes to book the hotel. You’ve probably figured it out; the application needs to parse, convert, and pass the check-in date/time in the new format for the request in hotel_book if the user decides to book the hotel.

This is just for one parameter! Imagine the complexity of this application if there are 50 or more data discrepancies across your APIs. The rule? The more consistent your design across API suites, the more an app developer can re-use existing code. Request and response parameters, status codes, error responses, the lot.

Fast forward five years. One hundred API teams have developed 2000 APIs for the flights, hotels, rail, rental car, and bus domains. At least five significant versions exist for each API. Sixty percent of your customers are still using v1. The ultimate complexity has turned into a major complication for the success of your customers and the success of your API program.

• Your company must now keep five versions of the same API “alive” as it’s too costly for your customers to version up.
• Remember, your application developers are creating their features and probably using other API technology providers.
• They have become so burdened with the upkeep of maintaining such a complex application using your APIs that it would take them years to version-up.

Don’t force your customers to shop the market for other API technology providers in your domain. Put together a design strategy within your organization to ensure consistency.

API management program. You guessed it: an API management program is a program to manage your APIs. Put together a design strategy within your organization to ensure consistency. This can be done in so many ways—programmatically and with API design “evangelists” and architects to lead design strategy across your organization. If programmatically, this is executed best via an API management platform (e.g., Apigee, Mulesoft, Kong) where teams can re-use standard design components, like data libraries. Also, API management platforms consist of an API gateway, which is infinitely configurable, so you’ll need an API gateway team to build, configure, and maintain it. Including the implementation of your pricing strategy, throttling, request authentication, and authorization.

4. The success of your API program depends on the success of your customer.

Imagine self-teaching yourself organic chemistry. Some of us could probably do it…with some pain and torture. But…why, though? Now imagine for a moment that your customers may experience some issues integrating your APIs. Easy to imagine! Actually, inevitable. Because it always happens.

Remember, you are the expert of your APIs. Develop a support model with your top experts in the loop.

Back to TomTom’s developer center as the prime example of how to do things right. I’m working on integrating TomTom APIs for a “pet project” startup application. And I decide to go the iOS SDK route to see if it could save some time. What have I done? I usually deal with raw API calls. I hate giving up, so I go to the TomTom portal “support” for help. (We’ll see how much longer I can tolerate the SDK integration approach. Seriously, one-word …storyboards. Okay, sorry; one more word…interface.) I submit a ticket late Friday night, early into Saturday morning, and I put my development on hold in the interim of an answer. Lo and behold, I get an answer back from one of their top experts on a Saturday! Granted, my issue was part user error (my impulse and literal interpretation of the documentation) but my expert was supremely polite and informative with his answer back. Fixed. Be like TomTom.

It must be engrained within your company culture to have the engineers needed and equipped to support the success of your customers.

From your communications team.

Let your customers know about all of the new features you’re launching! Again, go TomTom team. Geofencing is one of the primary features I need. As if I’m constantly checking your developer portal to see if you’ve launched new features? Uh…no. Let me know via email. And although I don’t need location history for my application, I do want virtual borders—can I set virtual borders without tracking user location? I’m going to check it out.

Let your customers know when you make changes to the code! Holy cow, again, these guys have their act together—I see you TomTom! Updating your design strategy in accordance with best practices…you clever foxes.

From your developer relations community.

Before I attended “API the docs” in Amsterdam I had no idea that TomTom had APIs, nor that I could use them for my pet project. Nor that they had a developer portal until I met and got acquainted with Julija Babre. After I gave a shout-out on LinkedIn of their developer portal, the swarm of their developer relations team contacted me (some directly) with their support.

From your product management community.

Last thing, look! Here’s a post from the product manager of the TomTom Maps SDK for Web asking for feedback! These guys seriously rock. I received this via email. (Again, don’t force me to refresh your developer portal to check whether there might be an update). Not only does a post like this help your developers prepare for integration, but it enables you to get product feedback and gauge success.

Turn your adopters into advocates. Make them feel like they’re part of your community.

Conclusion

The TomTom developer portal “sold me.” And it should also be clear in this article that TomTom has equipped their company from the ground-up to support the success of their developer portal, with their five critical developer portal elements, a well-oiled API machine, and developer relations and support community. It makes me “brand loyal.” It makes me want to be an advocate. And it makes me confident that they will continue to help to ensure my success in building my application.

And that, folks, is how you ensure the success of your developer portal. Be like TomTom. You have to design for the human experience from the ground up (from within your company).

“Cliff notes” summary

1. Application use cases. Research your customers to identify what kind of application your customers are creating. Web, mobile? What programming languages? For example, Java developers (usually large enterprises) care more about case conventions than other programmers.
2. Consistent API design. Put a design strategy in place to ensure consistency across your API suite long before you start thinking about exposing your APIs to the public on a developer portal.
3. Organizational change. Get your organization on board. Even better, get your executives on board! Open access to your APIs, transparent/explicit pricing models, and hiring the skillset internally needed for your application use cases (e.g., programming languages, SDKs).
4. API management program (and team). Organize an internal API management program to ensure the consistency of your design strategy. This may be via an API management platform (e.g., Apigee, Mulesoft, Kong) where teams can re-use shared data libraries. It may be through hiring central design “evangelist” architects to lead this design strategy across your organization. Reinforce this programmatically via a CI/CD pipeline to your developer portal.
5. API gateway team. If you go about this using an API management platform (recommended), you’ll need platform and software engineers to configure and support your API gateway. Things like throttling, OAuth 2.0 authentication, request signature, nonce (to prevent replay attacks).
6. API developer portal team. An API developer portal with a mini front-end web application for each endpoint (i.e., visual demo) is incredibly sophisticated. Go hybrid—externally to build and internally (accordingly) to support and continuously improve your developer portal. Collect user feedback continuously to measure success. Don’t forget about GDPR, collect minimal user information. (Note: some API management platforms have the developer portal component built-in.)
7. Product management team. Let your developers know when a release is available (as soon as you can) and get feedback before general availability.
8. Communications team. Marketing content writers for branded customer communications. Content writers for your portal copy. The best technical writers are capable of writing API and SDK documentation in step 1-2-3.
9. Customer success model. Build up a support and developer relations community with people centered around your organizational model to ensure customer success. Funnel customer feedback throughout your organization.
10. Developer portal. Finally, launch a developer portal with the critical elements that your application developers need to build and scale their application. Attention executives: The success of your developer portal and brand loyalty to your company depends on it.