Making a hit API is a lot like making a hit music album. You have to find a niche, you need good naming, and you need quality content. Also, on the production side, design, style, experience, and collaboration matter greatly. At the end of the day, both are products requiring the right management tools, marketing know-how, and infrastructure to scale.

In my SXSW-inspired opening keynote at the Austin API Summit 2024, I looked into the parallels between the two endeavors, considering some specific tips API providers should consider along the road toward becoming API platform rockstars. Below, I’ll review some of these points.

Specialization

Just like in music, “micro” is popular in technology. I remember my first iTunes music player, which classified music into broad groups, like pop, rock, classical, hip-hop/rap, and a few others. Nowadays, micro-genres proliferate the web, with large communities having emerged around hundreds of sub-genres like bedroom pop, breakcore, neo-folk, chillwave, and countless others.

The same thing has occurred in IT software. The monolithic systems that were once so prevalent have slowly been decomposed into microservices. Large software systems are now composed of many specialized components for discrete functions, such as authentication, payments, shipping, search, recommendations, and more.

In both industries, specialization matters. But how small is too small when designing an API? On average, APIs have 22 endpoints, found The Anatomy of an API 2023 report. In an interesting article, Bruno Pedro analyzed popular APIs and found that the ratio of operations per feature is below ten. So, although modern services are fine-grained, their capabilities should be organized to reduce perceived complexity.

Just as micro-genres have proliferated online, so have fit-for-purpose microservices architectures.

Experience

Are you (developers) experienced?

As Hendrix would say, “Are you experienced?” The experience you have listening to an album matters. A great album will take you on a musical journey. Similarly, the experience a developer has while consuming an API matters a lot.

Developer experience is becoming increasingly a defining trait for APIs in a competitive marketplace. This is underscored by the sheer number of APIs out there. For example, an F5 report on API sprawl from 2021 estimated that we’re approaching 200 million public and private APIs.

Developer experience can also reduce costs. DX unlocks cost savings through improved efficiency, creating more optimized cycle times, reducing support overhead, reducing employee churn, and making technology more accessible. Perhaps most importantly, developer experience helps retain happier users who champion your service through word of mouth—a tried-and-true marketing technique.

So, what does a great developer experience look like? I believe that a quality API developer experience includes public documentation, SDKs, code samples, and an OpenAPI specification that matches production mechanics. Moreover, APIs should enable instant playback. Like how a streaming platform allows a user to test snippets of songs (or stream them for free with ads), a developer portal should enable instant testing free so developers can assess if it’s a good or not before they buy in.

Naming

Just as in music, you need a good name.

One of my favorite album names is Random Access Memories by Daft Punk. (And a good double entendre for a tech blog, to boot). Just like in music, naming is important. It’s also challenging — some folks have cheekily said that coming up with variable names is the hardest part of being a developer.

When considering endpoint naming for REST APIs, there are many standard naming conventions, such as using resources as nouns, pluralized resources, forward slashes for hierarchy, and others. Following these tips will keep a web API more in line with modern DX expectations.

Quality

Shoot to create Steely Dan level APIs.

In the late ’70s, Steely Dan pioneered modern recording techniques using high-fidelity multi-track recording, which would become commonplace in the following years. Their album Aja, for example, is intentional, well-performed, well-produced, and precise. So, how do we create Steely Dan-level APIs?

One way is to compare runtime API performances against industry benchmarks. A service that does this is API Expert, which publishes weekly performance rankings for APIs grouped by specific domains, such as fintech, enterprise IT, and AI. These ratings give you an idea of the performance expectations for distributed computing, such as latency, pass and fail rates, and differences between cloud regions.

Another way to gauge quality is to test APIs at the design stage. I recently ran OpenAI’s YAML OpenAPI definition through several OpenAPI scanners that compare the schema against industry best practices. These found some inconsistent naming conventions, a lack of specific headers and operation descriptions, and other potential issues. API screening isn’t a replacement for great functionality, but it can help tweak things to improve overall quality.

Style

In both music and APIs, style matters.

One very stylish album is Loveless from My Bloody Valentine, which uses a lot of ethereal and dreamy, saturated effects. Just as it’s important for music producers to have an ear on the current style, it’s equally essential for API designers to consider the style they’re using.

Looking at modern trends, we see that REST is still a dominant architectural design style for web APIs. However, others are slowly gaining more of a foothold. Interestingly, in 2023, GraphQL finally outranked SOAP in popularity, according to the State of the API Report. Though SOAP is still a mainstay in many legacy environments, it has a more rigid XML-based format and is less likely to be used in greenfield API development, meaning its use will gradually wane over time.

Regarding other styles, developers may prefer webhook integration for specific applications so their applications don’t have to expend resources polling when waiting for a single event. GraphQL may be the best option for front-end developers because it can query multiple fields simultaneously, and so on. The takeaway is that REST is still a dominant force for building API products, but API designers should consider other design styles when appropriate.

Consistency

In music, you’re supposed to “find your sound.” Listeners typically like an artist with a consistent sound and aesthetic from album to album. Weezer is a prime example of this. Just look at their album covers, from the Blue album to the Green album, the Red album, and the Teal album, and you’ll see what I’m talking about.

Embrace consistency from API to API, just like Weezer album covers.

Your API catalog should look like this and bake consistency into the API design and developer experience. Because, a hodgepodge portfolio of disparate API styles, different URL structures, and various naming conventions, is just a recipe for poor developer experience and potentially even sprawl issues.

This can get even worse when managing an extensive API portfolio. Therefore, platform architects should consider adopting what Kristen Womack describes as “Similar Hallways” to standardize the flow for your developer support resources. This approach uses a consistent arrangement of getting started guide, documentation, code samples, and a sandbox for each API.

But taking this a step further, an API style guide is a good way to share conventions throughout your organization. The API Stylebook collects style guides from Atlassian, Cisco, Google, Microsoft, Heroku, and others. Google’s API Improvement Proposals is another example of this in practice.

Unfortunately, we can’t all be like The Beatles, pioneering various genres and evolving our sound from album to album. So, “find your sound” and stick with it in your developer-facing resources.

Cataloging

On that note, cataloging is another similarity between albums and APIs. Record labels typically assign an alphanumeric catalog number for every album they release. For example, the catalog number for the first pressing of The Beatles’ Abbey Road is “SO-383.” Software developers must also organize and keep track of their releases, right?

Albums have liner notes akin to technical documentation in the software world. Unfortunately, in the world of APIs, not all APIs are documented. In fact, a 2023 Enterprise Management Associates (EMA) report estimated that only 10% of APIs are documented. A lack of API documentation is a common pain point for developers and could exacerbate API discovery problems.

The number of APIs within a single large organization is steadily growing. (Rapid’s 2022 State of APIs report found companies with 10,000 or more employees tend to have over 250 internal APIs). Proper inventorizing of APIs is a first step toward keeping track of these endpoints. Keeping an active API catalog promotes discoverability and reusability and avoids unmaintained zombie APIs with employee turnover.

Productization

Michael Jackson’s “Thriller” has sold 70 million copies worldwide, making it one of the most commercially successful albums ever. Not only did the album have a ridiculous number of hit singles produced by the legendary Quincy Jones, but it was packaged and marketed well as a product. You need a business perspective around any successful project, or else it will fail in the market. This is true for albums and is true for APIs.

At Nordic APIs events and on the blog, we’ve traced the emergence of API-first thinking that embraces the API-as-a-product mantra. “The API is no different than another product,” said Jason Harmon, CTO of Stoplight and API Intersections podcast host, at The Platform Summit 2023. “The future of APIs is all about product management.”

To Harmon, treating your API as a product means seeing the overall network and relationship with your partners. It requires demonstrating business value and acquiring executive buy-in. He also advocates for a customer-first approach that informs API design. Other product-thinking techniques certainly apply to APIs, such as demonstrating business value, shipping early and iterating, and documenting the service well.

Bonus Track: Some APIs Are Just a One-Hit Wonder

Like those deep cuts on an album that aren’t many getting plays, APIs have their hit tracks, too. A study by Treblle recently confirmed this. As explained in The Anatomy of an API in 2023 report, the Treblle team analyzed over one billion requests across 9,000 APIs for trends and found that GET methods are, by far, the most popular type of API call.

But most interesting to me is that the report sheds light on the fact that many APIs are sitting inactive and unused. One in five API endpoints are zombie APIs, meaning that they haven’t been used by anyone in the last 30 days. One takeaway is to analyze your traffic and shutter APIs that aren’t used at all, which will help maintenance and security.

The other takeaway is to monitor your API usage. Knowing your high-traffic endpoints, or “one-hit wonders,” could help inform your true value proposition. Then, you can optimize the developer journey to focus more on this use case to truly reap the benefits of the “single,” that, let’s admit, people like playing again and again.

Security

Lastly, you gotta secure your intellectual property. In 2011, the famous electronic artist Skrillex lost an entire unreleased album after his laptops and hard drives were stolen. As in music and APIs, you have to secure your high-value resources. For APIs, this translates into the data, privileges, and systems that can be accessed through calls.

Unfortunately, many API endpoints are left exposed without the proper access control that authenticates the user and carefully considers their permissions. Some APIs improperly expose unnecessary amounts of data without rate limits, which could be scraped and sold on the dark web, as was the case with a Trello breach in early 2024. Other breaches arise from business logic gaps or leaky API keys, as occurred with exposures at Hugging Face and Kronos.

Due to gaps like these, API attacks are on the rise. In fact, Traceable’s Global State of API Security 2023 found that 60% of organizations said they had at least one API-related breach in the past two years. Such hacks can leave millions of user data points exposed, not to mention rack up considerable fines.

To avoid this, be concise. “One of the key learnings from a hit song is that it needs to be the right length and the right message,” says Jeremy Snyder, Founder and CEO of FireTail. “If a song is too long, it may lose that hit appeal.” If a song starts in one direction and then abruptly changes, listeners may switch it off, he adds.

Similarly, Snyder says API responses should be concise, returning precisely what the developer requests. Returning verbose fields could break the rule of least privilege and even lead to legal complaints for data leakage. Or, if your API invokes functions users didn’t request, they might be confused and lose interest, he adds.

Go And Be A Hit API Producer

Interestingly, there are plenty of other parallels between producing an album and producing an API. Both are team efforts, requiring the right tools and infrastructure to scale. You also need to market them and openly communicate about releases to the world. And, aside from some viral exceptions, neither becomes a star from day one — most groups iterate and improve their performance over time.

When it comes down to it, both are business endeavors, reminds Snyder. When you listen to a song, whether it’s on the radio or a streaming service, a cost is involved, either through a subscription fee or the ads associated with listening. The same is true for APIs, which are often directly monetized on a per-call basis. “You want to let the people who should be able to use the API use the API, but not others,” he says. Doing so requires solid authentication and authorization to control access.

So, there you have it — a handful of tips culled from the music industry that you can apply to producing APIs. Lastly, I’d encourage API designers to build everlasting technology. Design backward-compatible software creations that, like the music mentioned above, become universal and well-loved hits for years to come.