I’m sure you’ve used a third-party API at some point in your dev career – for example, to create new contacts in your CRM, to send emails through a newsletter service, or to do anything else with a third-party service virtually.

If you’ve interacted with a couple of such APIs, you will undoubtedly have noticed some differences between them: using one was probably more pleasant than the other. It’s easy to see which API was designed thoroughly, by an experienced developer, and perhaps with a lot of effort and thought. And it’s just as easy to be frustrated with an API that was designed poorly and sloppily. The former was probably a joy to use, while the latter was perhaps… not.

Since the effects are so visible, most developers tend to quickly agree that it’s almost a duty to design public APIs in a careful and thought-out way. Nobody wants to work with a crappy API – and nobody wants to burden other developers with using their API being crappy.

Modern software design puts great emphasis on the concept of “application programming interfaces”. However, as most developers already know, the idea goes a lot deeper and is not exclusive to a public interface. Instead, you should build APIs inside your application, for internal use, too.

Approaching these internal APIs in the same way you’d create a public one can make a huge difference: your colleagues (and you) will want to interact with this part of your application. Making the interaction as easy as possible for these people is one of the best goals you can have.

A secure, thoughtful API is probably the part of your software where quality matters the most. Your colleagues might forgive you a little sloppiness in the internals of this or that method. But they won’t (and shouldn’t) forgive you for creating a dangerous API.