On the face of it, coding may not appear to have much in common with disciplines like painting, poetry, or songwriting. But there’s a case to be made that, through its blend of analytical thinking and creativity, there’s just as much art in API design as any other creative pursuit.

At our Austin API Summit in 2024, David Biesack, Chief API Officer at Apiture, joined us to talk about the art of API design and the role that offering a compelling developer experience has in the adoption of, continued use of, and evangelism around different APIs.

Biesack defines API design as a translation process. “It’s taking requirements from your product team. So you’re building a new product, or you’re adding a new feature: you have to take those requirements, understand them, then map them into an API that delivers those capabilities so people can build applications on top of those APIs.”

But as automation and AI-driven code generation emerge as popular solutions to all technical problems, do we risk APIs becoming stale, artless, or even completely broken? Let’s find out.

Creativity vs. Developer Experience

In Rilo Kiley’s 2001 indie hit, Science vs. Romance, lead singer Jenny Lewis describes a jaded view of modern technology: “Text versus romance, you go and add it all you want. Still we’re not robots inside a grid, zeroes and ones.”

The takeaway is that technology can fall short when we come to rely too much on it. Looking at prominent recent AI fails, those lyrics continue to ring true today. But is there a point at which that will no longer be the case?

It’s easy to see how people skills and technical knowledge are relevant in Biesack’s description of API design. He calls the “most critical part of API design understanding the domain and then mapping it into an API.” Yet, there’s some conflict between this definition and the perception of API design as art, which is generally associated with creativity.

In fact, Biesack highlights that there are many ways in which creativity is actually at odds with providing a great developer experience, in that creativity:

• Shuns consistency in favor of novelty
• Ignores, or feels obliged to put some spin on, reuse
• May subvert existing standards for the sake of innovation
• Increases learning curves

In these respects, creativity for the sake of creativity may ultimately discourage API adoption. Biesack argues that APIs “must be utilitarian… and must value function over form, substance over style.”

An Axway blog post on beautiful APIs elaborates on how developers should strive for the “principle of least astonishment,” stating that “nothing should be jarring.” For instance, authentication tokens should utilize standard security practices, error codes, and intuitive messages.

It’s worth drawing some parallels with the art world here. The type of APIs Biesack is describing has a great deal in common with movements like minimalism or brutalism. Whether or not those aesthetics are to your taste, you probably wouldn’t say they’re “not art.”

Guiding Principles of API Development

Of course, no API is created in a vacuum. Biesack points out that there’s a scientific aspect to consider as well. He explains how we can study APIs, identify patterns, and use existing standards to evolve our practice and improve our APIs.

Some of the more “scientific” (as opposed to artistic) considerations of API design include:

• Domain analysis/modeling
• Attack vectors
• Compliance
• API Surface Area
• Clarity and completeness
• Ease of use and implementation

In that respect, Biesack argues, the art of API design is “the art of making decisions.” Does adding that extra endpoint make the product unnecessarily bloated? Is OAuth 2.0 the best option for securing this particular API? These are the sorts of questions API developers face daily.

In his talk, Biesack calls API design a “whole-brain activity.” It’s an act of intelligence that requires both the left brain (logical, analytical, linear) and the right brain (artistic, creative, imaginative) to succeed. In other words, it’s a holistic approach that balances art and science effectively.

And there’s certainly an art to knowing what to include and what not to include in a project, as Ernest Hemingway once colorfully told F. Scott Fitzgerald: “I write one page of masterpiece to ninety-one pages of shit. I try to put the shit in the wastebasket.”

This practice might sound familiar to any technical writers who have ever tried to create great documentation, another key component of API artistry, to back up their shiny new API.

Do New Trends Spell Trouble for API Design?

In theory, some concepts outlined above — minimalism, clarity, consistency — seem like things that AI and automation should excel at. In practice, that’s not always the case.

Biesack argues that we still require organic intelligence to ensure that the API in question is discoverable, comprehensible, and isolates clients from backend changes. In other words, these are some of the many things that make up good developer experience.

Above, Biesack offers compliance as a key tenet in API design. Let’s delve deeper into that. Compliance requires in-depth knowledge of the space in question (such as banking, finance, or healthcare) and total awareness of upcoming changes to regulatory practices and requirements. Failure to meet those requirements could be catastrophic for API providers.

It’s worth observing that, currently, gen AI tools used for development may lack up-to-the-minute knowledge of regulatory developments due to the lag in their training. Depending on the data they’ve been trained on, they may also lack the in-depth knowledge of the relevant space necessary to create a compliant API.

On the other hand, we’ve seen the rise of trends like standardization (see the benefits of using API specifications) and automation (see automatically generating SDKs for APIs). While these may not seem “artistic” in the traditional sense of the word, they’re doing great things for the adoption and consumption of APIs.

Although automation and AI could be valuable tools in API development, they don’t mean we can abandon the granular, nuanced thinking associated with the practice. Biesack observes that “AI is really just a software artifact” and lacks the subjectivity of an experienced developer. It’s still up to us to figure out the best way to solve a problem with APIs.

Conclusion: API Design Is an Art

We opened this piece with some relatively obscure lyrics (unless, perhaps, you spent your youth in Hot Topic or PacSun). So, let’s close out with a more mainstream take on all this:

“After a certain high level of technical skill is achieved, science and art tend to coalesce in esthetics, plasticity, and form. The greatest scientists are always artists as well.” – Albert Einstein

If Einstein is right about that, we should be listening hard to some of the concerns we’ve heard people voice around the risks of AI-generated code and the over-automation of the API space. “There’s really a lot more to API design than just plugging in a prompt and getting an answer back,” says Biesack.

That said, there are ways in which developer knowledge may ultimately extend to working with AI. “As you’re looking at adopting these tools…[you’ll be figuring out] which APIs you’ll use to train the generative AI, whether training data fits your domain, whether those API styles match your developers’ needs,” says Biesack.

Cesare Pautasso is an advocate for “beautiful APIs” and regularly delves into how things like structure and visual notation can influence an API’s appeal. He’s even written a book on the subject if this post sends you down the rabbit hole of artful APIs…

That’s the dichotomy of API design: as much as designing an API is about technical knowledge and standardization, it’s also about creating solutions that demonstrate an understanding of users’ needs, match (or exceed) their expectations, and make developers’ lives easier.

Which is, of course, true of most art forms: music requires a knowledge of scales and keys as well as raw passion, great literature needs correct grammar, and so on. So, if you really want to call yourself an “API Artist” on LinkedIn, you won’t hear any objections from us.