Every Developer is an API Designer

Tue, 25 Apr 2017 13:35:04 +0000

Every function; every class; every struct and enum and protocol is an API.

YOU — are an API designer

As developers, we move into and out of the role of “API Designer” constantly.

Have you ever thought about that? You are an API designer! You create Application Programming Interfaces all the time.

I believe that everything we create has design built in, whether we’ve thought much about it or not.

I don’t know why that thought changed my mindset so much, but it did. Maybe it’s because I always associated APIs with massive frameworks, standard libraries, and 3rd party code modules. It’s as if I thought there was a special class of developer that did that work, and all my job entailed was putting the jigsaw puzzle together.

But when you and I design and create Types of any kind, be they data structures or functions, we ourselves, as “regular developers”, are in the business of creating APIs. We’re building ways for ourselves and others to “connect” to and interact with our code… to interface with it and use it in order to perform work.

You may be building these things for your team to use, or you may be building them for the future [you] to use. The fact is, we slip in and out of consuming and creating APIs all the time.

Being mindful of shifting roles

It’s been helpful for me to recognize when I shift in and out of each role, because creating an API applies a different aspect of the programming mind than consuming an API does.

When you create an API, you’ve got to be super conscious of your decisions. Types matter. Names matter. Inputs, outputs, dependencies and the like all matter when you’re creating an API. Why?

Because other people (or you!) will have to deal with what you create in a direct way. Sure, everyone might be concerned about the implementation and whether or not it has bugs or not. But they’ll be most concerned about how to use the thing… the API… to get work done.

When we drop out of the mode of designing and creating APIs into API consumer mode, we experience the ramifications of our API designs directly.

“Why is this property named that??”
“Does this function really need all these parameters?”
“This function returns what?”
“I wish this concept was represented as a ___ instead of a ___…”

When you’re cognizant of what you’re doing with respect to creating and consuming APIs, it’s a huge help to your team and to [future you].

APIs and team mates

I was working with a teammate, and we were having a discussion about the Type of a property in a class we were building together.

The original API was a property of Type String, and the name of the property was FieldNames. I thought to myself, “Huh… FieldNames… plural… Why is this Typed as a String? Either the name should be singular, or the Type should be switched out.”

We ended up switching that out to a Type that conveyed the idea of being able to store multiple things in that property.

The point? Something as small as the letter s and the Type of a property made a head-scratching difference in my understanding of the API. I didn’t know how to use it until I asked. And that’s a tiny bit dangerous if the person who built it isn’t there to ask, anymore, right?

#1 Takeaway

The number one takeway I want you to glean is this: Whether you realize it or not, if you’re in the software development business, you’re in the API design business. For me that meant becoming super conscious of the kind of code I’m writing, depending on which role I’m in as the keystrokes flow. Maybe this realization will impact you as well!

API Design on Andrew Bancroft

Every Developer is an API Designer

YOU — are an API designer

Being mindful of shifting roles

APIs and team mates

#1 Takeaway