API Wisdom You Should Know - Code and Chats with Ken

Think of an API (Application Programming Interface) as a digital tool that software developers use to build their work. Developers use APIs making video games, mobile apps, websites, and email services. In fact, any type of software that offers a solution for a customer uses APIs.

APIs help developers deliver faster, and with greater quality.

Growing a Platform Based on APIs

It used to be that delivering APIs was limited to a certain type of company. For a long time it was limited to the domain of a handful of large businesses creating proprietary systems. For example:

Microsoft Windows
Sony PlayStation
Apple Mac

Now we see a diverse ecosystem of APIs from ambitious providers having a unique set of data, or novel ways of manipulating data.

Some API providers have evolved into platforms. They have offered so much value, that crowds of active users have grown around them. That draws the attention of new content providers who arrive to enhance the platform with novel capabilities. They acquire new customers, and more deeply engage current ones. Examples:

Salesforce
Unity Game Engine
Java
Apple iOS

APIs are no longer limited to the domain of only software developers. APIs have become big-business worthy of your attention.

Profit from Learning About APIs

I've spent decades using APIs building my computer programs. I've spent years being part of an API company dedicated to supporting the global travel and tourism industry. I've studied the industry leaders.

Here's a collection of my thoughts on APIs. My aim is explaining the technology, design, and use to a general audience. People like you.

Reach out to me on Twitter or LinkedIn if you want to share your response to my work.

I hope this helps you!

It's Not Too Late to Learn About APIs

Thousands of software developers have completed decades of defining work on APIs. You may feel left behind, and that there's no way to reasonably catch up. Don't despair. There's still time to prosper by mastering concepts like these:

OpenAPI specification files
Postman
JSON
Documentation
GraphQL design
Developer experience

Some of those concepts are covered here. Others are more technical, take more room to explain, and are topics for you to study further as time permits.

"How to Use" API Instructions

Every great product comes with directions. Maybe you don't need them but it feels reassuring having them around just in case you do. Same with API products. Here are the types of documentation to deliver alongside your APIS:

Getting started
API reference
Deep-dive tutorials
Change logs
Migration guides
Cut-and-paste sample code

Recommendation: API product managers should partner with technical writers to create outstanding instructions.

APIs Are Made for People

APIs aren't made for two computers to talk together, they're made for people to communicate.

How do developers feel using your APIs? You might think it's funny asking that question - because you wonder if developers even have feelings. We do, and you want them to be positive ones when using your APIs. Remember, they have a choice in selecting technology providers.

Recommendation: API product managers partner with user experience pros to create outstanding feelings.

When You Offer APIs to the World

You should offer an API when you do something good, and other people want to be able to do that good too. Difficult and valuable things like:

Access to well-structured data
Orchestrating a complicated industry
Transforming real-world assets into digital ones

Ultimately you focus on users with problems, you offer a solution, and you're able to capture some of the value you create.

API-first Companies Leverage their Own Work

A key aspect of an API-first mindset means being "customer-zero" by using the same web services you're offering customers. Makes sense.

If you managed a Starbucks store you'd drink the coffee, at Volvo you'd drive the cars, at On you'd exercise in the shoes.

How can you use an API if you're a non-programmer? There's an emerging path: No-Code/Low-Code platforms. It's your entry-point for becoming a real user of your APIs. To gain empathy for your users. Look into this topic if it's interesting for you.

Good Developer Experience is Key to Great APIs

Why is developer experience (DX) important enough to draw special attention to it as compared to UX we already know about? I've learned this about software developers as users:

Highly specialized and uniquely technical
Serve as top-influencers to company decision makers
The API audience is relatively smaller and business stakes are higher

Pro-tip: If you support the API sales funnel you need to offer industry-leading DX because converting the limited prospects into paying customers is crucial.

We programmers are builders, we want to do hands-on experiments before we accept new tech, and we'll find out if the marketing is just fluff.

Discovering APIs

Prospective customers need to know you have fantastic APIs offering valuable services. A great "Developer Portal" is indispensable. It's a highly specialized website matching key needs of API evaluators, decision-makers, and users:

Showcase capabilities
Inventory individual APIs
Document everything for all styles of learners

A good Dev Portal is a highly-curated, self-serve, library of concrete instructional information. Help your technical users here. If you don't you'll leave them only one choice - calling Tech Support. That gets time consuming for both sides, and time is money.

Pro-tip: programmers hate being "sold to." Marketing teams, work with your in-house devs ensuring your content hits the right tone.

Reliable APIs Power Good UX

I think creating apps is awesome. I've been part of teams delivering apps on mobile native, open web, game console, and even email automation. Problem is, any one company doesn't have enough time and talent to deliver all the apps needed in the world.

Deliver APIs to grow your overall industry.

App developers benefit from reliable API providers who can enable teams to build awesome UX for their own users. They know them best after all.

Give the world APIs and discover how the market demand evolves.

API Billing Feels Like Home Utilities

When I think of the business of APIs I often think of utility connections like gas, electricity, and water. They need management:

Turning it on for new customers
Clearly measuring how much is used
Plain billing based on metered usage
Shutting off when customers don't pay

APIs have unique management needs too: security, throttling, versioning, balancing, logging.

API Management is a capability that many platform companies offer. Maybe you want to build your own. Maybe you leverage pay-to-play solutions like: Kong, Mulesoft, Azure, AWS, Apigee, or Mashery.

Public API Analysis Reports

I have tech-hero companies that I watch for inspirational content, implementation reference, and trending news. Some publish white-papers and reports surfacing industry trends. Here a couple of good ones:

Read them as time permits. Share your favorite takeaways on social media posts.

APIs are User Interfaces

"The interaction point between a human being and a computer system." That's my paraphrasing from reading many sources (far smarter than me) defining what a user interface is.

Does that describe an API for a software developer? Yes - absolutely! Clearly APIs have three key aspects to its UI:

The URL
The request sent up
The response received back down

Good API design is critical! It needs to be intuitive, efficient to use, and when possible, enjoyable. You'll recognize these as key attributes of fine product usability.

Recommendation: software architects should intentionally design their APIs to be used by people. Steal best practices from UX professionals to do a better job and win at business!

The Perfect Time to Launch Your API

When should you and your company build APIs and offer them to customers?

By the time you think you're ready, it's too late.

Technology Terms Around APIs

There's lots of industry jargon around APIs. Business people ask me about a few terms the most often. Here's a rough-and-ready, high-level way, to compare together the most common terms.

Architecture choice: SOAP, REST, GraphQL, gRPC
Data formats for requests and responses: XML, JSON, Protobuf
Communication protocol standard: HTTP

Which one is the best? Depends on the situation.

Relating to Your API Developer Users

Developer Relations is a crucial role if your company offers APIs or aspires to be a reliable platform making an industry programmable. This is a part of DX.

Consider getting started with some of the most fundamental DevRel activities:

Writing articles
Giving talks
Live coding
Community building

What do your customers need, hope, and fear about developer relations and API providers?

APIs vs SDKs

A great portfolio of APIs is easily used by a software developer. What if you want to make them even easier to use? You might choose to wrap your collection with language-specific software developer kits (SDKs) offering these additional capabilities:

Convert JSON/XML requests and responses into idiomatic data structures
Conveniently automate managing access tokens
Clean-up various inconsistencies in legacy API design

Delivering a SDK for popular programming languages like Java, PHP, C#, Node, Python, Ruby, Swift, can increase adoption because it feels more familiar to programmers. Which ones should you prioritize? Ask your customers.

Final Thoughts on APIs

That concludes my shared wisdom about APIs. We considered them from a technical, business, and design-oriented perspective as creators and consumers.

I hope you found something useful in my notions. Feel free to share them with anyone who my benefit from their content. Reach out to me on Twitter or LinkedIn if you want to share your response to my work. GL/HF!