It’s time to release an API. You may think that you’re wiring together some controllers, and scrambling to put together a documentation site. At the end of the day you hope to have an API that your co-workers and third parties can take for a spin.

Along the way, you’ve developed a language.

It’s a very special language, of course. It’s a language whose rules, words, and expressions are dedicated to communicating about the objects in your business domain. It’s not meant for writing the next best-selling novel.

But it’s a language all the same, and whether you know it or not, you’re now a practicing linguist. And that means you need to think carefully about the way this language you’re developing works.

There’s an ongoing debate in the dictionary community: are word definitions unchanging, or should they adapt to ongoing usage? If a word has traditionally been described as an adjective, but it’s commonly used as a sentence adverb - should the definition in a dictionary change and label that word a sentence adverb? Or do the dictionary editors leave the definition unchanged, so that the word is an adjective forevermore? Hopefully, this raging debate will be resolved soon.

There is a similar question in API management that we must address. Are API design rules fixed and unyielding, so that we look down our noses at those who would violate them? Or do we allow designs to shift with time, reflecting the way consumers want to use APIs, and developers want to write them?

I think there are valid opinions on both sides of the question. I tend to prefer a pragmatic point of view - which may just be an attempt to have my cake and eat it too. I certainly believe there are some very good guidelines for writing and consuming APIs, and following them gives all parties some great advantages. Designers should attempt to follow these guidelines whenever possible. However, when the rules get in the way, or become overly expensive or burdensome, it’s our responsibility to address that problem - and we should break rules along the way if need be. In some cases, I believe that breaking rules carefully and prudently can be much safer and productive than rigidly adhering to doctrine.

I think there are a lot of interesting problems in API management that can benefit from this sort of pragmatic approach, and I hope to examine those issues on this blog.

Image courtesy of Tamara Menzi