API Design Is Not a Requirement for All Devs but a Little Empathy Should Be

My friend Matthew Reinbold wrote a great post on his blog asking, "what if developers aren't meant to do API design?" I think he is touching on an important aspect of why DevOps might not work everywhere in the same expected ways. We all have our strengths, and we all have our weaknesses, and I agree with him that maybe we are asking too much of our developers—API design might not be their strength. 

As the owner of a small business operated by one person (me), DevOps is hard. I cannot do everything myself and require a variety of services to help me out, but I still hit areas where I'm deficient like graphic design and editing. I'm getting better at editing, but my graphic design skills never seem to evolve at all. I would like to think I can do everything, but I can't, and if I had a job at a large organization and was expected to learn every piece of a modern stack—I'm not sure I could do it.

Bringing it back to the API design, though, the question of who does API design still needs to be answered. It can't just be left behind because a developer of an API doesn't have the chops. Ideally, a company could afford to hire an API designer and architect to come in and work their magic, but I know, in reality, this isn't going to happen within many organizations. So, what can be done?

API Design in Our Tools and Services

Developers use language and platform specific IDE functionality as a crutch, and we need the same enablement for API design in leading API design tools and services. This is why projects like the API design stylebook are so important because they begin to provide us with the definitions that are needed to drive the advancements.

Sharing of Common API Patterns

I feel like such a nag on this subject, but we need to share the common API patterns more. If you are using HAL or Siren, share the story and definition of your approach. If you have OpenAPI Spec or API Blueprint, make them available. If you are a developer, go out and do a little discovery of existing patterns before you get to work. You don't need to be an expert, but do a little homework first.

Sharing of Common Data Patterns

This exists in the form of Schema.org. Don't reinvent the wheel when it comes to your underlying schema. Even if you are mapping to completely wacky sh*t behind, use common definitions on the front. Again, API design tooling and services need to pipe these into your solutions. Here are all the OpenlAPI specs for Schema.or to get you going. 

These three areas can help augment developers when API design is just not their cup of tea. After that, and short of hiring an API design professional, developers who are touching on the API layers are just going to have to step up and develop some empathy. I think API design is part science (specs, schema, patterns), and part empathy of everyone who will come in contact with that API. I don't require all developers understand hypermedia or REST, but they damn sure should be required to put some thought into who is going to be developing against the API and consuming it. Otherwise they shouldn't be developing an API in the first place.

Coming full circle, I guess this could be an argument for GraphQL, right? If you can't find developers who get API design, you can't hire an API professional, and for some reason they are empathy-challenged, you can provide a GraphQL layer that allows developers to get at what they need. IDK. This is one of the reasons I like web APIs (not just REST)—they allow for this bridging of the often very technical backend with the often very human interface on the front-end. I guess it also takes a willingness on developers to empathize with the fact that this exists and are willing to do a little extra work.